Skip to content
Development
Skill

/design-system-from-codebase

Use when the user wants a public design system site built from an existing app codebase (build mode), or wants an existing design system updated after the app changed (maintain mode). Audits the code, extracts tokens and components, and ships every change through one reviewed PR.

From plugin
ai-skills
22133 skills

Claude Code

$ npx -y skills add julianromli/ai-skills --skill design-system-from-codebase --agent claude-code

SKILL.md

design-system-from-codebase.SKILL.md
name: design-system-from-codebase
description: Use when the user wants a public design system site built from an existing app codebase (build mode), or wants an existing design system updated after the app changed (maintain mode). Audits the code, extracts tokens and components, and ships every change through one reviewed PR.

Design system from codebase

Turn an existing app repo into a professional, public design-system site: tokens, foundations, components, copyable code and a shadcn registry. Then keep it in sync as the app grows.

Pick the mode

  • **Build:** no design system exists yet. Run steps 0 to 5.
  • **Maintain:** a design system exists and the app changed. Skip to "Maintain mode".
  • If unsure, look for an existing DS repo or folder and a CHANGELOG.md with a sync point.

Hard rules

  • The app code is the source of truth. A design file (Figma, Paper, Wonder) is secondary.
  • Work on a branch. One PR per run. Never push to main and never merge without the user's explicit go. No force-push.
  • Before anything goes public, scan the ported code for secrets, internal URLs, customer data and private API shapes. Remove them.
  • Keep the app's brand. Copy only the structure and craft of a reference site, never its brand signature.

0. Intake (ask only what is missing)

  • App repo and target: a new repo or a folder in the app repo.
  • Optional design file.
  • Brand assets: product icon, company logo or wordmark.
  • Theme scope (light only, or light and dark). Public or private.
  • Reference site for polish. Default: Palermo, https://palermo.tryprofound.com.

1. Audit the codebase (read-only)

  • Stack: framework, styling (Tailwind version, CSS variables), component libraries (Base UI, Radix, shadcn), icon set, fonts.
  • Tokens the app actually uses: colours with semantic roles, type scale, radius, spacing, shadows, motion durations and easings, z-index, breakpoints.
  • Reusable components: variants, states, props, and how often each is used. Flag duplicates and one-offs.
  • Large app: start with the most-used components. List the rest as a backlog.
  • Design file present: diff it against the code. Code wins. Record the differences.
  • Write audit.md with the stack, tokens, component inventory, gaps and top issues by impact.
  • Send the user a short summary plus screenshots of the reference site. Confirm scope before you build.

2. Scaffold the site

  • Default stack: Vite, React, TypeScript, TanStack Router (file-based routes), Tailwind v4, the app's own primitives, pnpm, GitHub Pages deploy on push to main, PR checks on every PR. If the app is not React, match its framework.
  • Prefer one shared token source (a theme file or package) that the app and the site both import. If that is not possible yet, copy the tokens and note it as drift risk.
  • Pages: Overview, Installation, Foundations (Colors, Typography, Radius, Elevation, Motion, Icons, Layout, others found), Components grouped by job (Actions, Forms, Overlays, Data, Navigation, Feedback).
  • shadcn registry: r/theme.json plus r/<component>.json.
  • Port components without business logic or API calls. Keep the app's exact values.
  • Provenance (design-file names, code-only parts, design-vs-code diffs) goes in CONTRIBUTING.md, not on public pages.
  • Create CHANGELOG.md with version 1.0.0 and the sync point: the app commit SHA you audited.

3. Public polish (defaults; the app's own tokens win)

  • Top bar 56px: product icon, Search button with a Ctrl/Cmd+K command palette (dialog role, focus trap, arrow keys wrap, Enter opens, Esc closes, focus returns), GitHub link.
  • Sidebar: sentence-case groups, active item marked by a thin left line, no pills or badges, a filter field.
  • Page header: title 24/32 at weight 600, one lead line under 65ch, text-wrap balance, no overlines or jargon.
  • Content column about 800px. Component pages about 880px.
  • Specimen frame: one thin border, generous padding, no dot grid. Preview and Code text tabs inside the frame, Copy in the tab bar. Code in the app's mono at 13/20, line numbers hidden from screen readers.
  • Foundations as large specimens (type stack, swatch cards with wrapping token names), not tables.
  • Home: short intro, one primary CTA (install the theme), GitHub link, foundation tiles that show real tokens, compact component directory (2 columns on desktop, first-sentence descriptions, no truncation).
  • Footer: product name and version, source link, company credit ("By <Company>" wordmark linked to the company site).
  • Branding: product icon in the top bar, mobile drawer and favicons (32px PNG, 180px full-bleed apple-touch-icon). Optimise SVGs and strip generator comments. Use real logos in demos, never text placeholders.
  • Mobile at 390px: drawer nav, search button, 44px tap targets, 16px inputs, no page-level sideways scroll. Variant grids switch to stacked lists when columns do not fit.
  • Copy: plain English, short sentences, no internal jargon.
  • Motion: respect prefers-reduced-motion. Keyboard-opened UI like the palette opens without animation.

4. Review before the PR

  • Run a design review on the output: spacing, type, motion, accessibility, touch targets, AI-slop patterns. (If emil-* skills are available, use emil-ui-review, emil-unslop-design and emil-touch-and-accessibility.) Fix small issues. List larger ones.
  • Typecheck, lint, tests (include an accessibility test for the palette) and build must pass. Registry output changes only when intended.
  • Screenshots at 1440 and 390: home, one component page, typography, colors, the open palette. In maintain mode, before and after. Keep PR images on a separate assets branch so they never land in main.

5. Ship

  • Open one PR: change list per step, deviations from the plan, remaining issues, screenshots.
  • Iterate with new commits.
  • On the user's go: update the README (live URL, search, brand asset paths, CONTRIBUTING link), merge, then verify the deployed site (title, favicon, credit, search, no console errors).

Maintain mode (t

Read more
@julianromli
Ships withai-skills

A curated collection of AI agent skills for coding, frontend, debugging, product thinking, and workflow automation.

Stars on GitHub

Momentum

stars in total
221
Star history of julianromli/ai-skills on GitHub, a chart by star-history.com

Other skills on ai-skills.

agent-browser

agent-browser

Browser automation CLI for AI agents. Use when the user needs to interact with websites, including navigating pages, filling…

brainstorming

brainstorming

You MUST use this before any creative work - creating features, building components, adding functionality, or modifying behavior.…

clone-website

clone-website

Reverse-engineer and clone one or more websites in one shot — extracts assets, CSS, and content section-by-section and…

collapsible-sidebar

collapsible-sidebar

Use this when building a sidebar that collapses to an icon rail, or any element that toggles between shown and hidden. Labels…

More skills from other plugins.

brainstorming
Auto-invoked

brainstorming

You MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or…

@obra@obraInstall Skill
ask-matt

ask-matt

Ask which skill or flow fits your situation. A router over the skills in this repo.

skills2w309k
@mattpocock@mattpocockInstall Skill
accessibility
Auto-invoked

accessibility

Design, implement, and audit accessible UI to WCAG 2.2 Level AA across Web, iOS, and Android — semantic ARIA roles and labels,…

ecc2w293k
@affaan-m@affaan-mInstall Skill
compiler-commit

compiler-commit

Use when you want to verify compiler changes and commit with the correct convention. Runs tests, lint, and format, then commits…

react6d252k
@facebook@facebookInstall Skill

Questions about design-system-from-codebase.

Which coding agents can use design-system-from-codebase?
design-system-from-codebase installs in Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, OpenCode and Windsurf with the skills CLI, using each agent's flag shown on this page. Flowy's auto-invocation, which fires a skill when your prompt matches, runs in Claude Code only.