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.
In this repository8 other files it gives its agents.
- autopilot-executeSkill
- close-planSkill
- deep-modules-auditSkill
- docs-auditSkill
- execute-phaseSkill
- lint-fixSkill
- phased-planSkill
- responsive-auditSkill
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
- Distinctive: line 13
Real components, fixture data: Every preview imports and renders the actual component from the codebase.
- Distinctive: line 17
Screen shell pattern: Every screen in the app is split into two parts:
- Distinctive: line 62
Before building anything, understand what exists:
- Distinctive: line 191
Add a showcase in the components section
- Distinctive: line 195
Add to screen map with states and category
- Distinctive: line 196
Create fixtures if new data shapes are needed
- Distinctive: line 198
Add renderer to the barrel
- Distinctive: line 212
Never import upward. A component must not import a shell.
- Distinctive: line 216
Don't recreate components for the design system — import the real ones
- Distinctive: line 217
Don't require the backend to be running to view the design system
- Distinctive: line 218
Don't put fixture data inline in route files — centralize in fixtures/
- Distinctive: line 219
Don't skip states — if a screen has a loading state, make it previewable
- Distinctive: line 220
Don't treat this as documentation-only — it's a development tool
≈ “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.
Files
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
- Real components, fixture data. Every preview imports and renders the actual component from the codebase. No mocks, no copies, no approximations.
- 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.
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.
- Shell — a pure presentational component that takes props and renders UI. No data fetching, no routing, no auth. Lives in
- Every state is previewable. Shells accept a
stateprop (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. - 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 togetherProcess
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 (
useStatefor accordions, etc.) is allowed - Barrel export from
index.ts
Orchestrator rules:
- Thin — ideally <200 lines
- Derives
statefrom 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
- Build the component
- Add to registry
- Add a showcase in the components section
Adding a New Screen
- Extract the shell (presentation only)
- Add to screen map with states and category
- Create fixtures if new data shapes are needed
- Create a renderer
- 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 propsNever 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
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
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.

