[Julia Shilova (juliashilovaa)]

Problem

There is no single maintained place where designers, developers, and AI agents can see ThinkRail's actual components, usage rules, working code, and the design system behind them.

Design guidance is scattered across multiple specs (COLOR, TYPOGRAPHY, SPACING, NOTIFICATIONS, UI-TERMINOLOGY, and module specs). Token values are repeated manually, component previews can drift from production, and the external designer prompt references outdated fonts and colors.

Goal

The long-term goal is to build an AI designer that can review new features against the existing design system, identify inconsistencies, and suggest improvements.

The first step is to establish a single, reliable source of design knowledge that stays synchronized with production and can be used by both humans and AI agents.

Solution

A design-system library inside the existing ThinkRail frontend, covering foundations, components, patterns, and vocabulary.

The library uses actual production components and tokens, maintains design rules in one place, and generates Markdown documentation from the same sources.

1. Architecture

• apps/web/library is a second Vite entry of apps/web, using the existing React, React Compiler, Tailwind, and @/ alias setup.
• No additional dependencies and no impact on the application bundle.
• Components are imported directly from @thinkrail/ui/*, themes from @/themes.
• library.css imports the application's index.css, so the library renders with the exact production styles and tokens.
• Component changes hot-reload into the library.
• No duplicated components, copied styles, or manually recreated states.

2. Single source of truth

Token values remain in their original sources:

• colors.json, typography.json, spacing.json
• tokens.css and theme manifests

Design rules, descriptions, and component documentation live in apps/web/library/content/.

Instead of repeating token values in documentation, :::live blocks render directly from production sources.

15 live blocks cover color roles, alpha values, palettes across themes, typography, spacing, radius, icons, and themes.

The blocks reuse the existing token generators' logic (typographyModel.ts, colorsModel.ts) rather than introducing separate calculations.

3. Component documentation

Button and IconButton are the first fully documented components.

Each component page includes:

• Purpose, when to use, and alternatives.
• Live variants, sizes, tones, and states.
• Interactive playground with generated code.
• Copyable examples using actual production components.
• Anatomy, props, defaults, and accessibility.
• Keyboard behavior and usage rules.
• References to real production usage.

Component API documentation is type-checked against the actual TypeScript props, preventing documented variants, sizes, tones, and properties from drifting out of sync.

4. Library interface

The library is organized into five sections:

• Guides: component reuse and extension rules, design iteration prompt.
• Foundations: Color, Typography, Spacing, Radius, Icons, Themes.
• Components: searchable overview and individual component pages.
• Patterns: Notices, Loading.
• Vocabulary: shared UI terminology.

The interface includes a grouped sidebar, sticky page outline, live previews, collapsible code examples, and a theme switcher supporting all six production themes.

It uses ThinkRail's own typography, tokens, and components, with responsive navigation and a mobile drawer.

5. Generated documentation for AI agents

library/scripts/generate-md.ts generates documentation directly from library content:

• COLOR.md
• TYPOGRAPHY.md
• SPACING.md
• NOTIFICATIONS.md
• UI-TERMINOLOGY.md
• packages/ui/COMPONENTS.md
• Root DESIGN.md

Existing specs retain their paths, frontmatter, and identifiers, so existing references continue working.

DESIGN.md consolidates the design prompt with current themes, fonts, typography, spacing, radius, and available components. It replaces the outdated external designer prompt.

AGENTS.md identifies the library as the source of design rules, while existing specs link to the relevant library documentation instead of duplicating it.

6. Validation

Added automated checks to keep the library synchronized with production:

• Generated documentation is up to date.
• All authored Markdown pages and live blocks are registered.
• Internal links and source references resolve.
• Examples match their documentation.
• Referenced production usages still exist.
• Documented defaults match rendered defaults.
• Component API documentation passes TypeScript checks.

library:verify runs browser verification in Chromium, covering navigation, live blocks, search, themes, component states, accessibility behavior, code copying, and responsive layouts.

Verification results:

• 57/57 library browser checks passed.
• Library build and generated documentation checks passed.
• Typecheck passed (25/25).
• Application CSS verified against main: no new classes, only unused Markdown-derived classes removed.
• No shipped runtime changes.

7. Commands

bun run library:dev
bun run library:build
bun run library:md
bun run --cwd apps/web library:verify [url]

Screenshots

Guides

Using the library	Design iteration prompt

Foundations

Color	Typography

Spacing	Radius

Icons	Themes

Components

Components overview	Button

IconButton

Patterns

Notices	Loading

Vocabulary

UI vocabulary

[jetbrains-air]

Approved — ready to merge.

[github-actions]

🌐 Website preview

Preview	https://pr-951.thinkrail-website.pages.dev
Routes	Landing · Blog · Vibecoding · Agentic development · Agentic IDE
Commit	fd8a0bd

This comment updates in place on every push that touches the website or shared build inputs.

[jetbrains-air]

Approved — ready to merge.

[jetbrains-air]

Approved — ready to merge.

[jetbrains-air]

Approved — ready to merge.

[jetbrains-air]

Approved — ready to merge.