design-foundation
Skill30 starsChanged 5 months agoMITView on GitHub
Create or extract a design-token foundation — colors, typography, spacing, radii, shadows — as a real tokens file (CSS variables and/or Tailwind theme) plus a migration map from current hardcoded values. Use when the user says 'set up a design system', 'our styles are inconsistent', 'we have 50 shades of the same blue', 'add design tokens', 'formalize our design', 'make new features match', or when starting a new frontend that needs a foundation before building screens. Also the first step whenever other design work keeps fighting ad-hoc values. Produces the tokens file, a global→semantic token structure wired for dark mode, and a short list of the worst drift to migrate first.
2 other projects use a version of this.
Adopted by
Most recently taken up by
- Koroqe/claude-code-sdlctheir own version, first seen Oct 23, 2026
- 5throck/ai-workspace-standardstheir own version, first seen Sep 26, 2026
Other versions2 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 2
- Koroqe/claude-code-sdlc★ 52same name
- 5throck/ai-workspace-standards★ 25same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository39 other files it gives its agents.
- brand-assetSkill
- creative-strategistSkill
- image-generationSkill
- orchestratorSkill
- original-designSkill
- product-photographySkill
- product-videoSkill
- remotion-script-writerSkill
- social-graphicsSkill
- talking-headSkill
- accessibility-excellenceSkill
- color-systemSkill
- component-architectureSkill
- design-engineer-mindsetSkill
- error-handling-recoverySkill
- frontend-orchestratorSkill
- interaction-physicsSkill
- layout-systemSkill
- loading-statesSkill
- performance-optimizationSkill
- typography-systemSkill
- visual-hierarchy-refactoringSkill
- brand-voiceSkill
- content-atomizerSkill
- direct-response-copySkill
- email-sequencesSkill
- keyword-researchSkill
- lead-magnetSkill
- newsletterSkill
- orchestratorSkill
- positioning-anglesSkill
- seo-contentSkill
- seo-strategySkill
- tweet-writerSkill
- product-design-reviewSkill
- fable-like-implementationSkill
- foundation-sprintSkill
- sol-orchestratorSkill
- sprint-runnerSkill
The file
We split this skill into the rules it gives an agent
7 rules. About 0 are common, 4 are distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈4
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 12
Use to create tokens from scratch or extract them from an existing codebase.
- Very specific: line 13
If the user's pain is specifically color (palette, contrast, dark mode depth) → skills/frontend-design/color-system after the token …
- Very specific: line 14
If specifically type (scale, fonts, readability) → skills/frontend-design/typography-system.
- Very specific: line 15
If they want components built on tokens → skills/frontend-design/component-architecture next.
- Distinctive: line 20
Before asking anything, gather evidence:
- Distinctive: line 43
Extraction rule: when existing values cluster (15px, 16px, 17px), collapse to the scale value closest to the most frequent.
- Distinctive: line 76
Write the tokens into the detected entry point (don't create a parallel system beside an existing one — extend it).
≈ “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
Design Foundation
Produce a working tokens file for this specific codebase — not a document about tokens. A token is a named design decision (--color-text-primary, --space-4); centralizing them is what makes every later design skill (layout, type, color, components) land consistently. Governing principle: extract before you invent — in an existing codebase, the token system should formalize the best of what's already there, so migration is renaming, not redesigning.
When to use / handoffs
- Use to create tokens from scratch or extract them from an existing codebase.
- If the user's pain is specifically color (palette, contrast, dark mode depth) →
skills/frontend-design/color-systemafter the token skeleton exists. - If specifically type (scale, fonts, readability) →
skills/frontend-design/typography-system. - If they want components built on tokens →
skills/frontend-design/component-architecturenext. - For broad "where do I start" requests →
skills/frontend-design/frontend-orchestrator.
Step 1 — Inspect the codebase
Before asking anything, gather evidence:
- Find the current styling entry points. Glob
tailwind.config.{js,ts,cjs,mjs},**/globals.css,**/index.css,**/app.css,**/*theme*,**/tokens*. Read them. - Detect the stack. Tailwind v4 (
@import "tailwindcss"+@themein CSS) vs v3 (config filethemeobject) vs CSS Modules / styled-components / vanilla CSS. Checkpackage.jsonfor the tailwindcss version. - Measure drift. Grep source for
#[0-9a-fA-F]{3,8}\b,rgba?\(,hsla?\(→ count distinct colors. Grep for\d+pxand Tailwind arbitrary values\[(\d+px|#)→ count rogue spacing/size values. These counts go in your rationale. - Find the de facto system. Sort found values by frequency. The most-used font sizes, spacing steps, and colors are the candidate tokens.
- Check dark mode (
dark:,prefers-color-scheme) — determines whether the semantic layer must ship two modes now.
Step 2 — Intake
Ask in one batch, only what's missing: brand color (or "pick for me"), product feel (dense data tool vs. spacious marketing/consumer), and dark mode now or later. Infer everything else. Don't stall: if the codebase already answers these (an obvious brand blue, an existing dark: usage), state assumptions and proceed.
Step 3 — Build the token system
Two layers minimum, three when a component library exists:
- Global tokens — raw values: a neutral ramp (50–950, tinted toward the brand hue, never pure grey), the brand ramp, semantic status colors (success/warning/error/info), a spacing scale on a 4px base (4, 8, 12, 16, 24, 32, 48, 64), font sizes, radii, shadows, z-index steps, transition durations.
- Semantic tokens — meaning, referencing globals:
bg-primary/secondary,text-primary/secondary/tertiary/inverse,border-primary,interactive-primary/hover/active/disabled. This is the layer that flips for dark mode — components only ever consume semantic tokens. - Component tokens — only if a component library exists or is planned next (
--button-primary-bg: var(--color-interactive-primary)).
Decision rules:
- Tailwind v4 → define tokens as CSS variables in
@themein the main CSS file. Tailwind v3 →theme.extendin the config, with semantic layer as CSS variables referenced from the config. No Tailwind → plain CSS custom properties on:root(+.darkor media-query block). - Extraction rule: when existing values cluster (15px, 16px, 17px), collapse to the scale value closest to the most frequent; list every collapse in the migration map.
- Naming: kebab-case, category-first (
--color-text-primary,--space-4,--radius-md). Match Tailwind's names where Tailwind is present, so utilities keep working.
Canonical shape (CSS variables; adapt to the detected stack)
:root {
/* global */
--gray-50: #F8FAFC; --gray-500: #64748B; --gray-900: #0F172A; /* full 50–950 ramp, brand-tinted */
--brand-500: #3B82F6; --brand-600: #2563EB; /* full ramp */
--space-1: 0.25rem; --space-2: 0.5rem; --space-4: 1rem; --space-8: 2rem;
--radius-md: 0.375rem; --shadow-md: 0 4px 6px -1px rgb(0 0 0 / 0.10);
/* semantic — the only layer components touch */
--color-bg-primary: var(--gray-50);
--color-text-primary: var(--gray-900);
--color-text-secondary: var(--gray-600);
--color-border-primary: var(--gray-200);
--color-interactive-primary: var(--brand-600);
--color-interactive-hover: var(--brand-700);
}
.dark {
--color-bg-primary: var(--gray-950); /* dark gray, never #000 */
--color-text-primary: var(--gray-50);
--color-text-secondary: var(--gray-300);
--color-border-primary: var(--gray-700);
}Full three-layer taxonomy, Tailwind v3/v4 wiring, and the variant/responsive-token patterns: read references/token-architecture.md when building the complete file.
Step 4 — Write the file and migrate the worst offenders
- Write the tokens into the detected entry point (don't create a parallel system beside an existing one — extend it).
- Migrate 1–3 of the highest-traffic files (the ones your grep showed drifting most) as a demonstration, replacing raw values with tokens.
- Produce the migration map for the rest.
Required output format
Deliver code plus this summary:
## Tokens file
[path written, e.g. src/app/globals.css or tailwind.config.ts — full contents]
## Decisions
| Decision | Choice | Why |
| Stack wiring | Tailwind v4 @theme / v3 config / CSS vars | [detected how] |
| Neutral tint | [hue] | matches brand [color] |
| Spacing base | 4px | [most existing values already multiples / default] |
| Dark mode | now via .dark class / deferred | [user answer or inference] |
## Migration map (worst drift first)
| Found in code | Count | Replace with |
| #3c82f7, #3B82F6, #3a80f0 | 23 | var(--color-interactive-primary) |
| padding: 13px / p-[13px] | 9 | var(--space-3) (12px) |
| ... |
## Migrated now
[files actually edited as demonstration]
## Next step
[Which skill consumes this — typically skills/frontend-design/typography-system or color-system]Quality bar (check before delivering)
- Every semantic text/background pairing meets WCAG AA (4.5:1 normal text, 3:1 large text) in both modes if dark mode shipped
- Spacing scale is a single geometric-ish progression on one base; no orphan steps
- Neutrals are brand-tinted (nonzero saturation), no
#808080/ pure#000 - Components/examples reference only semantic tokens, never globals directly
- Token names collide with nothing existing; Tailwind utilities still resolve
- Migration map covers every value cluster found in Step 1, each mapped to exactly one token
- No second parallel token system introduced
Integration
- Consumes: maturity diagnosis + drift counts from
skills/frontend-design/frontend-orchestrator(if it ran). - Produces the tokens file consumed by:
skills/frontend-design/typography-system(extends the type tokens),skills/frontend-design/color-system(extends the color ramps + dark mode),skills/frontend-design/layout-system(spacing + breakpoints),skills/frontend-design/visual-hierarchy-refactoring(refactors screens onto tokens),skills/frontend-design/component-architecture(component layer).
References
references/token-architecture.md— full three-layer token taxonomy with complete listings, Tailwind v3 and v4 wiring, and patterns for dark mode, component variants, and responsive tokens. Read when writing the complete tokens file or wiring an unfamiliar stack.
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.

