design-systems
Skill8 starsChanged 28 days agoMITView on GitHub
V3 design harness — discovery brief gate, DFS pipeline, 12-dimension binary audit, OKLCH colors, jakub.kr micro-details. Produces world-class designs for any vertical.
20 other projects use a version of this.
Adopted by
Most recently taken up by
- adymire/CraftLayertheir own version, first seen Nov 15, 2026
- ldaume/agentic-engineering-harnesstheir own version, first seen Nov 8, 2026
- naman10parikh/pennyword for word, first seen Nov 8, 2026
- hamzzaqureshi/gravidextheir own version, first seen Nov 8, 2026
- AxlZero21/Skillstheir own version, first seen Nov 8, 2026
- memi-design/design-skillstheir own version, first seen Nov 8, 2026
Other versions20 projects use a version of this.
Word for word · 4
- naman10parikh/agentgrid★ 9100% same
- naman10parikh/penny★ 0100% same
- naman10parikh/pixel★ 0100% same
- naman10parikh/turbo★ 0100% same
Edited · 0
None found.
Wrote their own version · 16
- Mindrally/skills★ 275same name
- cuellarfr/design-skills★ 94same name
- nahid-sparktales/agent-dispatcher★ 59same name
- nimadorostkar/Claude-Skills-collection★ 37same name
- codetesla51/skills★ 32same name
- reddygopalkrishna/developer-agent-skills★ 8same name
- memi-design/design-skills★ 7same name
- botirkhaltaev/botir-skills★ 4same name
- ldaume/agentic-engineering-harness★ 3same name
- AxlZero21/Skills★ 1same name
6 more not listed
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 repository31 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- llms.txtllms.txt
- agent-runtimeSkill
- frontend-designSkill
- architectSkill
- deep-thinkSkill
- ecosystem-referenceSkill
- fractal-delegationSkill
- harness-reviewSkill
- heartbeatSkill
- integrate-resourcesSkill
- llm-council-critiqueSkill
- loop-createSkill
- mcp-setupSkill
- memory-compressionSkill
- memorySkill
- model-routingSkill
- oss-project-scaffoldSkill
- playwright-cliSkill
- repo-scoutSkill
- self-improveSkill
- skill-creatorSkill
- skill-routingSkill
- sprintSkill
- test-visualSkill
- troubleshootSkill
- ux-auditSkill
- wikimem-ingest-pipelineSkill
- wikimem-observerSkill
- wikimemSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
16 rules. 0 are common, 14 are distinctive, and 2 are very specific to this project.
0
Common
Most of the 15 edited versions we read keep these.
14
Distinctive
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 58
Gate check: If any of the 7 questions above is unanswered or vague, STOP.
- Very specific: line 82
HARD GATE: Before ANY visual work, map the eye-tracking path for every section.
- Distinctive: line 101
Use modular type scale (Major Third 1.25 ratio: 48→36→28→22→18→16→14→12px)
- Very specific: line 105
Gate check: If ANY section lacks a FIRST/SECOND/THIRD map, STOP.
- Distinctive: line 115
If I had to describe this brand as a physical space, what would it look like?
- Distinctive: line 117
If I remove all color and imagery, does the typography alone convey the brand?
- Distinctive: line 148
If autonomous, pick the strongest match.
- Distinctive: line 182
Write the complete decision log
- Distinctive: line 185
What gets killed: All rejected alternatives for every decision.
- Distinctive: line 281
Never use brand accent for success states (green reserved)
- Distinctive: line 316
What gets locked: All shape values — radius, borders, shadows, spacing.
- Distinctive: line 335
Verify each component against the decision log's rules
- Distinctive: line 336
Document any component-specific exceptions (with reasons)
- Distinctive: line 360
No data → CUT or add metrics
- Distinctive: line 385
If 3+ dimensions fail: go back to the failing step and re-iterate
- Distinctive: line 386
If 0-2 dimensions fail: apply fixes and ship
“Common” is measured: kept by at least 6 in 10 of the 15 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Design Systems V3 — DFS Pipeline with Discovery Gate
Transforms any design request into a premium, vertical-appropriate visual system. V3 changes: discovery brief is a HARD GATE (no brief = no design), DFS methodology (one component to 100% before scaling), 12-dimension binary audit (pass/fail, not vague scores), OKLCH color system, jakub.kr micro-details.
Quality bar: $100M agency output. Every step produces opinionated choices. Safe, generic options are not options.
Core philosophy: "What would a highly opinionated designer build to make this ICP resonate deeply with this vision?" — If you can't answer this, you haven't done Step 1.
The 12-Step V3 Pipeline
Each step: decisions made, options presented, what gets killed and why, what gets locked, output format. Decisions LOCK at each step and never get revisited.
NEW in V3.1: Step 1.5 (Information Hierarchy Map) added between Discovery Brief and Leading Questions. Based on Axieomatic design feedback. See knowledge/info-hierarchy.md for full rules.
NEW in V3.2: Visual Minimalism rules enforced. 70% visual, 30% text. Every section needs animation. Whitespace IS content. See knowledge/visual-minimalism.md. Also read knowledge/frontend-bible-2026.md (700-source research) before every design task.
Step 1: DISCOVERY BRIEF (Gate — No Brief = No Design)
HARD GATE. This step must produce a complete brief before ANY visual work begins. If the brief is incomplete, the pipeline stops. No exceptions. This is the #1 lesson from V2: jumping to visuals without strategy produces generic output.
Questions the brief MUST answer (Socratic self-interrogation):
- How much time was spent building the ethos of what we're building?
- What's the ICP — specific person, not demographic? Name, age, role, company size, daily frustrations.
- Is it for the upper end of the market? Mid market? Mass consumer?
- What's the goal of this page? Convert to sign-up? Book a call? Download? Purchase?
- What feeling should the user have within 3 seconds of landing?
- What are 3 products this ICP already uses and loves? (Design must feel native to that ecosystem)
- What would make this ICP say "finally, someone gets it"?
Process:
- Parse the request into structured brief fields
- Detect vertical from context clues (fintech, health, creative, devtools, consumer, enterprise, education, ecommerce)
- Define the target user as a SPECIFIC person — "Marcus, 42, portfolio manager at a mid-size hedge fund" not "finance professionals"
- Establish 3-word brand voice
- Identify 3 competitors and state how we DIFFER (not just who they are)
- Define the single conversion goal
- Define the target emotion (3-second test)
Gate check: If any of the 7 questions above is unanswered or vague, STOP. Do not proceed to Step 2. Ask the questions or research the answers.
What gets locked: Audience, voice, positioning, goal, emotion. These cannot change in later steps.
Output:
## Discovery Brief
- **Vertical:** fintech
- **Target user:** Marcus, 42, portfolio manager at a mid-size hedge fund. Uses Bloomberg Terminal daily. Frustrated by noisy consumer apps that waste his time.
- **Market position:** Upper-end institutional. NOT consumer, NOT mass-market.
- **Brand voice:** precise, confident, unhurried
- **Not this:** NOT Robinhood (gamified), NOT Bloomberg (overwhelming), NOT Webull (noisy)
- **Page goal:** Book a demo call
- **Target emotion:** "This is serious software built by people who understand my work"
- **ICP's beloved products:** Bloomberg Terminal, Notion, Linear
- **Value prop:** "Institutional-grade analytics that respects your attention"Step 1.5: INFORMATION HIERARCHY MAP (Gate — No Map = No Code)
HARD GATE. Before ANY visual work, map the eye-tracking path for every section. See knowledge/info-hierarchy.md for full rules.
For each section, write:
### Section: [Name]
- FIRST (0-1s): [Element] — [text] (size, weight, alignment)
- SECOND (1-2s): [Element] — [text] (size, weight, color)
- THIRD (2-3s): [Element] — [text] (size, weight, elevation)
- AMBIENT: [Supporting elements] (smallest size, lightest weight, muted)Rules:
- Maximum 3 priority levels per section
- Font weight → size → elevation → alignment → spacing must tell the SAME story
- Left-align by default. Center only with explicit justification.
- Vary container types: flush, inset, full-bleed, card, inline highlight, split. Cards for max 40% of sections.
- Use modular type scale (Major Third 1.25 ratio: 48→36→28→22→18→16→14→12px)
What gets locked: Per-section hierarchy map. This map becomes the blueprint for CSS — every font-size, font-weight, text-align, margin, and box-shadow decision references it.
Gate check: If ANY section lacks a FIRST/SECOND/THIRD map, STOP. Complete the map before writing code.
Step 2: Leading Questions (Sonnet)
Socratic self-interrogation before touching pixels. The designing agent argues with itself to sharpen the brief into visual direction.
Questions to ask and answer:
- If I had to describe this brand as a physical space, what would it look like?
- What's the ONE thing this page must communicate that no competitor does?
- If I remove all color and imagery, does the typography alone convey the brand?
- What's the most common mistake designs in this vertical make? How do I avoid it?
- What would a user who HATES this product say? How does the design preemptively address their objection?
Process:
- Answer each question in writing (minimum 2-3 sentences per answer)
- Identify contradictions between answers
- Resolve contradictions by choosing the stronger position
- Extract 3-5 visual principles from the answers
What gets locked: Visual principles (e.g., "density signals competence," "whitespace signals premium," "serif signals authority").
Output: 5 answered questions + 3-5 extracted visual principles.
Step 3: Visual Direction (Sonnet)
5 opinionated options, kill 4. Present visual directions from knowledge/visual-directions.md with provisional tokens. Pick ONE. No blending.
Process:
- Load
knowledge/visual-directions.md - Present all 5 directions with:
- One-paragraph pitch tailored to the discovery brief
- 3 reference brands
- Risk assessment for this specific vertical
- Provisional token preview (fonts, colors, shape, motion)
- Score each direction against the brief's visual principles from Step 2
- Recommend ONE direction with rationale
- If autonomous, pick the strongest match. If interactive, present and wait.
What gets killed: 4 directions. Record why each was killed. What gets locked: The surviving direction's philosophy, reference brands, and provisional tokens.
Step 4: DFS Hero Component (Sonnet)
Pick ONE component. Iterate to 100%. Document every decision.
This is the core V3 change. Instead of designing all components at 85% (BFS), pick the single component that carries 60% of the page's emotional weight and perfect it.
Process:
- Load
knowledge/dfs-methodology.md - Identify the hero component based on ICP type:
- Enterprise buyer → social proof / logo bar
- Developer → code example / terminal demo
- Consumer → hero headline + CTA
- Investor → metrics dashboard
- Creative → visual showcase
- Finance → data table / chart
- Iterate the hero component through ALL decisions:
- Typography (size, weight, tracking, line-height)
- Color (brand moment, surface, text contrast)
- Spacing (padding, margins, gaps — on 4px grid)
- Border radius (concentric rule applied)
- Shadows (multi-layer, OKLCH colors)
- Animation (hover, active, enter, exit)
- States (default, hover, active, focus, disabled, loading, error, empty)
- Responsive (mobile, tablet, desktop)
- Micro-details (from
knowledge/micro-details.md)
- For EACH decision: try 3-5 options, pick one, kill the rest with reasons
- Write the complete decision log
What gets locked: The hero component's complete specification. What gets killed: All rejected alternatives for every decision.
Output: Decision log (see knowledge/dfs-methodology.md for format) + hero component code.
Step 5: Decision Log (Sonnet)
Document WHY, record killed alternatives. This step formalizes the hero component's decisions into scalable rules.
Process:
- Extract every decision from Step 4's iteration
- For each decision, record:
- The choice made (exact value)
- 3+ alternatives tried
- Why each alternative was killed
- The rule extracted for scaling
- Organize into categories: typography, color, spacing, shape, animation, micro-details
What gets locked: The complete decision log. This is the design system's constitution.
Output:
## Decision Log
### Category: Shape
#### Border Radius: 8px (cards)
- Tried: 4px (too sharp), 6px (close, lacked warmth), 12px (bubbly), 16px (cartoon)
- Winner: 8px — professional warmth without consumer-app feel
- Scaling rule: cards=8px, buttons=6px, inputs=6px, modals=12px, tooltips=4px
### Category: Shadow
#### Elevation: 4-layer system
- Tried: 1-layer (flat), 2-layer (better but CGI), border+shadow (dated)
- Winner: 4-layer (outline + contact + ambient + far) using OKLCH
- Scaling rule: All elevated elements use the 4-layer tokenStep 6: Typography System (Sonnet)
12-level scale, OKLCH-aware, negative tracking on headings.
Process:
- Load
knowledge/typography-systems.md - Match vertical to recommended pairings (2-3 candidates)
- Present candidates with the full 12-level scale
- Select the pairing that best matches the visual direction
- Lock EXACT values — no "approximately 14-16px" ranges
- Apply tracking rules: negative on headings, positive on small text
12-level scale:
| Level | Use | Size | Weight | Tracking | Line-height |
| display | Hero headline | 56-72px | 400-500 | -0.03em | 1.05-1.1 |
| h1 | Page title | 40-48px | 500-600 | -0.025em | 1.1-1.15 |
| h2 | Section title | 30-36px | 500-600 | -0.02em | 1.15-1.2 |
| h3 | Card title | 24-28px | 500-600 | -0.01em | 1.2-1.25 |
| body | Main text | 16px | 400 | 0em | 1.5-1.6 |
| bodySm | Secondary text | 14px | 400 | 0.01em | 1.5 |
| caption | Metadata | 12px | 400-500 | 0.02em | 1.4 |
| label | Form labels | 12px | 500-600 | 0.04em | 1.3 |
| monoLg | Code blocks | 15px | 400 | 0em | 1.6 |
| monoMd | Inline code | 14px | 400 | 0em | inherit |
| monoSm | Terminal | 13px | 400 | 0em | 1.5 |
| monoXs | Badges/tags | 11px | 500 | 0.02em | 1.3 |
What gets locked: Complete 12-level scale with exact values + font loading code.
Step 7: Color System (Sonnet)
OKLCH palette, enforcement rules, ONE brand moment per page.
V3 replaces hex/HSL with OKLCH for perceptually uniform color. See knowledge/oklch-color-system.md.
Process:
- Load
knowledge/oklch-color-system.mdandknowledge/color-theory.md - Define brand color in OKLCH:
oklch(L% C H)— anchor at the 500 shade - Generate 11-shade scale using the OKLCH generator (keep H+C constant, vary L)
- Define surface elevation system in OKLCH
- Validate contrast using OKLCH L-difference (body text: 60%+ L difference)
- Define enforcement rules:
- ONE brand-colored moment per page (not per viewport — per PAGE)
- Brand color budget: max 3 elements per viewport
- Never use brand accent for success states (green reserved)
- Dark mode: flip L values (+25%), keep H+C identical
What gets locked: Full OKLCH palette + surface system + enforcement rules.
Output: TypeScript tokens with OKLCH values.
Step 8: Shape Language (Sonnet)
4px base, concentric radius, multi-layer shadows.
Process:
- Load
knowledge/layout-patterns.md+knowledge/micro-details.md - Apply visual direction's shape preferences
- Lock radius per element type (concentric rule: outer = inner + padding)
- Define 4-layer shadow hierarchy using OKLCH
- Generate complete spacing scale (4px base, 12 values: 4-96px)
Shadow hierarchy (OKLCH):
--shadow-sm: 0 0 0 1px oklch(20% 0.01 60 / 0.3), 0 1px 2px oklch(0% 0 0 / 0.15);
--shadow-md:
0 0 0 1px oklch(20% 0.01 60 / 0.3), 0 1px 2px oklch(0% 0 0 / 0.1),
0 4px 8px oklch(0% 0 0 / 0.08);
--shadow-lg:
0 0 0 1px oklch(20% 0.01 60 / 0.3), 0 1px 2px oklch(0% 0 0 / 0.1),
0 4px 8px oklch(0% 0 0 / 0.08), 0 12px 24px oklch(0% 0 0 / 0.05);
--shadow-glow: 0 0 40px
oklch(var(--brand-H) var(--brand-C) var(--brand-L) / 0.08);What gets locked: All shape values — radius, borders, shadows, spacing.
Step 9: Component Scaling (Sonnet)
Scale the hero component's decisions to ALL variants.
This is where DFS pays off. The hero component's decision log becomes the system.
Process:
- List all remaining components needed (from discovery brief)
- For each component, apply the hero's extracted rules:
- Radius from decision log
- Shadow from decision log
- Animation timing from decision log
- Typography level from scale
- Color application from enforcement rules
- Verify each component against the decision log's rules
- Document any component-specific exceptions (with reasons)
- Apply micro-details from
knowledge/micro-details.md:- text-wrap: balance on headings
- tabular-nums on numbers
- Concentric border radius on nested elements
- Multi-layer shadows on elevated elements
- Image outlines on dark backgrounds
- Stagger animations on groups
What gets locked: Component manifest with token application spec.
Step 10: Page Composition (Sonnet)
Emotional arc, background rhythm, max-w-2xl for text.
Process:
- Load
knowledge/page-composition.md - Map sections to 6-beat emotional arc:
- Recognition (hero) → Awe (social proof) → Trust (features) → Continuity (testimonials) → Conviction (pricing) → Action (CTA)
- Apply section cutting rules:
- Restates hero → CUT
- No data → CUT or add metrics
- Breaks arc order → MOVE or CUT
- Could be a tooltip → MERGE
- Assign background rhythm (alternating transparent + muted)
- Designate the ONE brand moment section
- Set content widths: text=max-w-2xl, grids=max-w-5xl, layout=max-w-7xl
- Define scroll animations:
opacity 0→1, y 16→0, 0.4s, ease-out, stagger 0.06s
What gets locked: Section list, beat mapping, spatial composition.
Step 11: 12-Dimension Audit (Binary Pass/Fail)
Replace vague scoring with binary pass/fail on specific metrics.
Each dimension is PASS or FAIL with a SPECIFIC measurement. No "7/10." No "could be better." Either it meets the bar or it doesn't, and if it fails, the FIX is explicit.
See council/scoring-rubric.md for the complete 12-dimension rubric.
Process:
- Load
council/scoring-rubric.md - Evaluate the output against all 12 dimensions
- For each FAIL: document the specific violation and the exact fix
- If 3+ dimensions fail: go back to the failing step and re-iterate
- If 0-2 dimensions fail: apply fixes and ship
Ship criteria: 10+ PASS out of 12 dimensions. Zero red flags.
Knowledge Base
| File | Purpose |
knowledge/visual-directions.md | 5 opinionated visual directions with provisional tokens |
knowledge/typography-systems.md | 15 type pairings with full 12-level scales |
knowledge/color-theory.md | Color psychology, signal rules, enforcement, dark mode |
knowledge/oklch-color-system.md | V3 OKLCH palette generation, dark mode flipping, contrast checking |
knowledge/micro-details.md | V3 12 jakub.kr micro-details that separate premium from generic |
knowledge/dfs-methodology.md | V3 Depth-first design: hero to 100%, then scale |
knowledge/layout-patterns.md | 4px grid, shape language, bento grids, content widths |
knowledge/page-composition.md | Emotional arc, background rhythm, scroll animations |
knowledge/anti-patterns.md | 26-pattern diagnostic checklist with remediations |
knowledge/ux-principles.md | Design heuristics for agent interfaces |
knowledge/animation-philosophy.md | Motion design principles and timing specs |
Vertical Profiles
| File | Domain |
verticals/fintech.md | Financial services, trading, banking |
verticals/health.md | Healthcare, wellness, fitness |
verticals/creative.md | Creator tools, design, music, video |
verticals/devtools.md | Developer tools, CLIs, IDEs, APIs |
verticals/consumer.md | Consumer apps, social, lifestyle |
verticals/enterprise.md | B2B SaaS, admin panels, CRMs |
verticals/education.md | EdTech, LMS, learning platforms |
verticals/ecommerce.md | Retail, marketplaces, storefronts |
Integration Points
- Energy design rules (
.claude/rules/design.md): Warm black, Instrument Serif + Poppins, bento grids, shadcn + 21st.dev - Agent UX spec (
docs/design/AGENT-UX-DESIGN-SYSTEM.md): State machine, tool timeline, generative UI cards - React patterns (
.claude/rules/react.md): RSC, Tailwind, shadcn/ui, Zustand - Anti-pattern enforcement (
knowledge/anti-patterns.md): 26-pattern checklist, must score 0-2 to ship
Quick Start
# Full V3 pipeline for a fintech dashboard
# Invoke: /design-systems
# Input: "Build a portfolio analytics dashboard for institutional investors"
# → Discovery brief (GATE) → Leading questions → Visual direction → DFS hero →
# Decision log → Typography → Color (OKLCH) → Shape → Scaling → Composition → Audit
# Quick audit of an existing design
# Load council/scoring-rubric.md → 12-dimension binary pass/fail → Fix failures
# Generate OKLCH palette for a brand color
# Load knowledge/oklch-color-system.md → generateScale(hue, chroma) → tokensDoes 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.

