agentleFS
khairoldkhairold/claude-skills/skills/living-design-system/SKILL.md

living-design-system

Skill0 starsChanged 7 months agoMITView on GitHub

Build a living design system that renders real app components with fixture data, independent of the backend. Use when setting up a design system, adding a design system to an existing app, or when the user wants to do pure UI development without running the full app stack.

The file

Show its rules and text

We split this skill into the rules it gives an agent

13 rules. About 0 are common, 13 are distinctive, and 0 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈13

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 0

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Real components, fixture data: Every preview imports and renders the actual component from the codebase.

    line 13
  2. Distinctive:

    Screen shell pattern: Every screen in the app is split into two parts:

    line 17
  3. Distinctive:

    Before building anything, understand what exists:

    line 62
  4. Distinctive:

    Add a showcase in the components section

    line 191
  5. Distinctive:

    Add to screen map with states and category

    line 195
  6. Distinctive:

    Create fixtures if new data shapes are needed

    line 196
  7. Distinctive:

    Add renderer to the barrel

    line 198
  8. Distinctive:

    Never import upward. A component must not import a shell.

    line 212
  9. Distinctive:

    Don't recreate components for the design system — import the real ones

    line 216
  10. Distinctive:

    Don't require the backend to be running to view the design system

    line 217
  11. Distinctive:

    Don't put fixture data inline in route files — centralize in fixtures/

    line 218
  12. Distinctive:

    Don't skip states — if a screen has a loading state, make it previewable

    line 219
  13. Distinctive:

    Don't treat this as documentation-only — it's a development tool

    line 220

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Living Design System

Build an in-app design system that uses actual components — not recreations or screenshots. The design system is a route in the app itself, but loads instantly without authentication, backend, or data fetching. It is the primary tool for pure UI development.

Core Principles

  1. Real components, fixture data. Every preview imports and renders the actual component from the codebase. No mocks, no copies, no approximations.
  2. Zero backend dependency. The design system route must bypass auth, database, and API layers entirely. If the backend is down, the design system still works. Achieve this by short-circuiting auth/loading gates in the root layout when on design system routes.
  3. Screen shell pattern. Every screen in the app is split into two parts:

    • Shell — a pure presentational component that takes props and renders UI. No data fetching, no routing, no auth. Lives in src/screens/{name}/.
    • Orchestrator — a thin route file that wires hooks, router, and state derivation into shell props. Lives in app/ (or your routing directory).

    The design system renders shells directly with fixture data. The app renders the same shells with live data. Same component, two consumers.

  4. Every state is previewable. Shells accept a state prop (e.g., 'loading' | 'empty' | 'data' | 'error'). The design system provides a state switcher so every state can be viewed without reproducing it in the real app.
  5. Single source of truth. A registry file lists all components and screens. Sidebar navigation, counts, and cross-references derive from it automatically. Add to the registry → it appears in the design system.

Architecture

app/design-system/          ← Routes (layout, pages)
  _layout.tsx               ← Sidebar + content shell, no auth
  index.tsx                 ← Foundations: colors, typography, spacing, shadows
  components.tsx            ← All component showcases
  screens.tsx               ← Visual sitemap of all screens
  screens/[slug].tsx        ← Individual screen preview with state switching

src/design-system/          ← Data layer
  registry.ts               ← Component + screen catalog (single source of truth)
  screen-map.ts             ← Screen entries: slug, states, category, deps
  fixtures/                 ← Static mock data (quotes, users, clients, etc.)
    index.ts                ← Barrel export
    {domain}.ts             ← Per-domain fixtures (empty, few, many variants)
  renderers/                ← Screen renderers: (state) → shell JSX with fixtures
    index.ts                ← Barrel: slug → renderer map
    {screen-name}.tsx       ← One per screen

src/components/design-system/ ← Presentation helpers
  ShowcaseCard.tsx          ← Wrapper for component demos (name, description, live preview, usage snippet)
  PhoneFrame.tsx            ← Device frame for screen previews
  StateSwitcher.tsx         ← Horizontal pill bar for toggling screen states
  SectionWrapper.tsx        ← Section header + content wrapper
  ScreenPreview.tsx         ← PhoneFrame + StateSwitcher + metadata panel
  sections/
    TokensSection.tsx       ← Color, typography, spacing, shadow showcases
    ComponentsSection.tsx   ← All component showcases composed together

Process

1. Audit the Codebase

Before building anything, understand what exists:

  • What framework/router? (Expo Router, Next.js, React Navigation, etc.)
  • What styling system? (Tailwind/NativeWind, StyleSheet, styled-components, etc.)
  • Where do design tokens live? (CSS variables, theme file, constants)
  • How many shared components exist? List them.
  • How many screens exist? Which ones have clean separation between UI and data?
  • Is there an auth/provider wrapper in the root layout? This must be bypassed.

2. Bypass Auth for Design System Routes

In the root layout, detect when the user is on a design system route and skip auth loading screens and redirect logic. The design system must render immediately.

Pattern (adapt to your router):

// In your root navigator/layout
const segments = useSegments(); // or usePathname(), etc.
const isDesignSystem = segments[0] === 'design-system';

// Skip auth redirects
useEffect(() => {
  if (isDesignSystem) return;
  // ... normal auth redirect logic
}, [isDesignSystem, ...]);

// Skip loading screen
if (!isDesignSystem && isLoading) {
  return <LoadingScreen />;
}

3. Extract Screen Shells

For each screen, separate presentation from business logic:

Shell rules:

  • Props only — no hooks that touch network, auth, or routing
  • State is a string union: type ScreenState = 'loading' | 'empty' | 'data' | ...
  • IDs are string, not framework-specific branded types
  • Callbacks are optional props: onSelectItem?: (id: string) => void
  • useColorScheme() is allowed (presentational)
  • Local UI state (useState for accordions, etc.) is allowed
  • Barrel export from index.ts

Orchestrator rules:

  • Thin — ideally <200 lines
  • Derives state from hook results
  • Passes callbacks that call router.push(), mutation(), etc.
  • Return is a single <Shell state={state} ... />

4. Create the Registry

A single file that catalogs every component and screen. The sidebar and all counts derive from this.

Component entry: name, slug, description, source path Screen entry: slug, name, route, description, category, available states, component dependencies, whether the shell is extracted

5. Create Fixtures

Static mock data for every domain object in the app. Provide variants:

  • MOCK_{ITEMS}_EMPTY — zero items (empty state)
  • MOCK_{ITEMS}_FEW — 2-3 items (sparse)
  • MOCK_{ITEMS}_MANY — 5+ items (typical)
  • Composed fixtures for complex screens (combine base fixtures into screen-specific shapes)

Fixtures must never import from the backend/API layer. All data is hardcoded.

6. Create Renderers

One file per screen. A renderer is a function that takes a state string and returns the shell with appropriate fixture data:

export function renderSettingsShell(state: string): React.ReactNode {
  switch (state) {
    case 'loading': return <SettingsShell state="loading" />;
    case 'data':    return <SettingsShell state="data" user={MOCK_USER} />;
    default:        return null;
  }
}

Barrel export as a Record<string, (state: string) => ReactNode> keyed by screen slug.

7. Build the Design System Layout

A web-optimized layout with:

  • Sidebar — auto-derived from registry. Shows foundations, components (with deep links), and screens (grouped by category, collapsible).
  • Content area — renders the active page.
  • Dark/light toggle — switches theme for the entire design system.
  • Back to app link — easy escape hatch.

8. Build the Pages

Foundations — Render real token values from your theme:

  • Color scales with hex values for both light/dark
  • Typography scale with live text samples
  • Spacing scale visualization
  • Shadow/elevation levels

Components — One showcase per component, each showing:

  • Live interactive preview (the real component, not a picture)
  • Brief description
  • Collapsible usage snippet

Screens (sitemap) — Grid of all screens with:

  • Category grouping (tabs, details, forms, auth, etc.)
  • State count per screen
  • Shell readiness indicator
  • Navigation to individual preview

Screen preview — For each screen:

  • Device frame (phone dimensions) with the shell rendered inside
  • State switcher bar to toggle between all states
  • Metadata panel (route, category, component dependencies)

Key Conventions

Naming

  • Fixture arrays: MOCK_{DOMAIN}_EMPTY, MOCK_{DOMAIN}_FEW, MOCK_{DOMAIN}_MANY
  • Composed fixtures: FIXTURE_{SCREEN}_{VARIANT}
  • Shell types: {Screen}State, {Screen}ShellProps
  • Renderers: render{Screen}Shell

Adding a New Component

  1. Build the component
  2. Add to registry
  3. Add a showcase in the components section

Adding a New Screen

  1. Extract the shell (presentation only)
  2. Add to screen map with states and category
  3. Create fixtures if new data shapes are needed
  4. Create a renderer
  5. Add renderer to the barrel

Dependency Direction

tokens (CSS/theme)     ← lowest level
  ↑
components             ← uses tokens only
  ↑
screen shells          ← composes components + tokens
  ↑
orchestrators (routes) ← wires hooks + router → shell props
design system          ← wires fixtures → shell props

Never import upward. A component must not import a shell. A shell must not import an orchestrator.

What NOT to Do

  • Don't recreate components for the design system — import the real ones
  • Don't require the backend to be running to view the design system
  • Don't put fixture data inline in route files — centralize in fixtures/
  • Don't skip states — if a screen has a loading state, make it previewable
  • Don't treat this as documentation-only — it's a development tool

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.