agentleFS
hueyexehueyexe/frontend-agent-skills/design-systems-frontend-architecture/SKILL.md

design-systems-frontend-architecture

Skill6 starsChanged 4 months agoMITView on GitHub

Use when building reusable frontend systems, design tokens, component contracts, responsive layouts, CSS strategy, or design-system documentation and governance.

The file

Show its rules and text

We split this skill into the rules it gives an agent

56 rules. About 0 are common, 51 are distinctive, and 5 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈51

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 5

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Use this skill when the user asks for any of the following:

    line 19
  2. Distinctive:

    Do not use this skill as the primary lens when the task is mainly:

    line 29
  3. Distinctive:

    Separate function from perception: Treat functional patterns as behavioral/interface modules and perceptual patterns as the style, tone, …

    line 40
  4. Distinctive:

    Use these defaults unless the user provides context that clearly calls for a different choice.

    line 53
  5. Distinctive:

    Default model: use a layered system: foundations/tokens → primitives → components → compositions/templates → product examples/pages.

    line 63
  6. Distinctive:

    Default documentation: every reusable pattern gets purpose, anatomy, variants, states, accessibility contract, content guidance, responsive …

    line 65
  7. Distinctive:

    Default governance: use light curation. Allow contribution, but require review for new tokens/components and require evidence before adding …

    line 66
  8. Very specific:

    Default naming: use role and state rather than raw appearance.

    line 72
  9. Distinctive:

    Default override rule: do not introduce a new token for a single exception.

    line 73
  10. Distinctive:

    Default breakpoints: use only enough breakpoints to protect readability, navigation, and task completion.

    line 78
  11. Distinctive:

    Default density: start with moderate density and generous scanability.

    line 79
  12. Distinctive:

    Default content testing: test with real or realistic content, including long labels, missing images, empty data, error states, loading …

    line 80
  13. Distinctive:

    Default JS: do not use JavaScript for effects CSS handles reliably.

    line 87
  14. Distinctive:

    Default custom controls: start with native controls.

    line 88
  15. Distinctive:

    Default focus: all interactive controls need visible focus and keyboard operation.

    line 95
  16. Distinctive:

    Ask only when the answer materially changes the system.

    line 101
  17. Distinctive:

    Ask a focused question when any of these are unknown and relevant:

    line 103
  18. Very specific:

    When asking, include a recommended default and options.

    line 112
  19. Distinctive:

    Use the question-tool-ready prompts in references/decision-prompts.md.

    line 114
  20. Distinctive:

    When reviewing an existing UI, design system, component library, or frontend implementation, inspect in this order:

    line 118
  21. Distinctive:

    When creating a new recommendation, proceed in this order:

    line 135
  22. Distinctive:

    Choose the smallest useful system slice: Do not start with an exhaustive component catalog.

    line 138
  23. Distinctive:

    Inventory existing patterns: Look for repeated functions, repeated styles, duplicated code, inconsistent names, and recurring states.

    line 139
  24. Distinctive:

    Validate: Run quality, accessibility, responsive, performance, and maintainability checks before finalizing.

    line 147
  25. Distinctive:

    Use this sequence before recommending a pattern or architecture:

    line 152
  26. Distinctive:

    Do not create a component from a screenshot alone.

    line 170
  27. Distinctive:

    Prefer fewer components with well-defined variants over many near-duplicates.

    line 171
  28. Distinctive:

    Every component needs examples with realistic content and at least one edge case.

    line 174
  29. Distinctive:

    Use semantic tokens for meaning and primitive tokens for palette/scale management.

    line 179
  30. Distinctive:

    Do not let product teams consume raw primitives directly when a semantic decision is available.

    line 180
  31. Distinctive:

    Do not solve one-off needs by expanding the token set before checking whether the need is recurring.

    line 181
  32. Distinctive:

    Document usage rules before implementation trivia.

    line 186
  33. Distinctive:

    Keep documentation close enough to code or design source-of-truth that it does not drift.

    line 189
  34. Distinctive:

    Treat names and glossary entries as part of the product architecture.

    line 190
  35. Distinctive:

    Never recommend custom controls unless you also specify how the native semantics and interactions are preserved.

    line 215
  36. Very specific:

    Start from the native element that already carries the needed behavior: button, a, input, select, textarea, details, dialog, list elements, …

    line 221
  37. Distinctive:

    Use headings and landmarks to preserve meaningful page structure.

    line 222
  38. Distinctive:

    Use ARIA only when native semantics are insufficient, and keep ARIA state synchronized with actual UI state.

    line 223
  39. Distinctive:

    Keep component responsibilities small and explicit.

    line 227
  40. Distinctive:

    Use composition for complex organisms and templates.

    line 229
  41. Distinctive:

    Use tokens for recurring values.

    line 235
  42. Distinctive:

    Keep specificity low; avoid deeply nested selectors and page-location dependencies.

    line 236
  43. Distinctive:

    Prefer layout primitives and component-contained responsive rules over scattered page-level overrides.

    line 237
  44. Distinctive:

    Use modern layout tools such as flex and grid when supported by the project constraints.

    line 238
  45. Distinctive:

    Use CSS for presentation, transitions, and state styling when CSS can handle the behavior accessibly and reliably.

    line 239
  46. Very specific:

    Avoid !important except for intentional utility layers or known override boundaries.

    line 240
  47. Distinctive:

    Test components independently and inside representative templates.

    line 245
  48. Distinctive:

    Avoid assuming fixed dimensions unless the content and platform truly enforce them.

    line 246
  49. Distinctive:

    Treat narrow viewports, high zoom, and large text as first-class cases.

    line 247
  50. Distinctive:

    Avoid shipping duplicate component implementations.

    line 251
  51. Distinctive:

    Avoid large dependency additions for small presentational problems.

    line 252
  52. Distinctive:

    Use build tools to automate repeatable tasks, but do not choose tools for novelty alone.

    line 253
  53. Distinctive:

    Add visual regression tests to high-value components and templates where UI drift would be costly.

    line 254
  54. Distinctive:

    Before finalizing work, verify:

    line 259
  55. Distinctive:

    Use the full checklists in references/checklists.md.

    line 273
  56. Very specific:

    Use concrete language. Prefer “Use one Inline validation component with success, warning, and error variants” over “make validation …

    line 302

≈ “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

Design Systems Frontend Architecture

Purpose

Help an agent convert UI, UX, product, and brand decisions into a durable frontend system: reusable components, tokens, layout rules, state behavior, documentation, governance, and implementation guidance that can scale across screens, teams, devices, and time.

Optimize for actual product work. Do not merely describe design systems. Produce decisions, defaults, component contracts, implementation guidance, critiques, and next steps the user can act on.

When to use this skill

Use this skill when the user asks for any of the following:

  • Design-system strategy, component libraries, pattern libraries, style guides, design tokens, UI kits, component audits, interface inventories, or governance.
  • UI critique, redesign, frontend implementation plans, component decomposition, responsive layout guidance, CSS architecture, or frontend maintainability.
  • Turning mockups, screenshots, UX flows, or product requirements into scalable frontend components.
  • Documentation for components, tokens, accessibility states, usage guidance, or design-to-code handoff.
  • Resolving inconsistency across UI surfaces, duplicated patterns, ad hoc styling, or component drift.

When not to use this skill

Do not use this skill as the primary lens when the task is mainly:

  • Broad UX research planning, ethnography, discovery interviews, market research, or product strategy not yet connected to UI/system decisions.
  • Visual art direction, illustration style, campaign creative, or brand identity creation unless the user is converting it into system rules.
  • Pure backend architecture, API design, data modeling, or infrastructure.
  • One-off static graphic design where reuse, accessibility, and frontend implementation do not matter.

Core principles

  1. Design systems, not pages. Scope effort by components, templates, content types, states, integrations, and behaviors rather than by page count.
  2. Think simultaneously in parts and wholes. Evaluate tokens, atoms, components, sections, templates, and real pages together. Do not design a component without checking how it works in realistic compositions and content.
  3. Separate function from perception. Treat functional patterns as behavioral/interface modules and perceptual patterns as the style, tone, motion, spacing, color, and type treatments that create product character.
  4. Start with purpose before abstraction. A component exists to solve a user or product problem. Do not create abstractions from visual similarity alone.
  5. Use shared language as infrastructure. Names, definitions, usage rules, and examples are part of the system, not decoration around it.
  6. Prefer reusable primitives, but preserve product distinctiveness. Consistency should reduce user effort and team waste; it should not erase useful brand expression or signature moments.
  7. Make the system the source of truth. Changes to shipped UI should update the component, token, or guideline where appropriate; avoid isolated hotfixes.
  8. Treat accessibility as a component contract. Semantics, keyboard behavior, focus, contrast, hit areas, error handling, and reduced-motion behavior must be specified with the pattern.
  9. Choose frontend architecture early enough to prevent debt, but keep it adaptable. Establish conventions before implementation spreads, then revise them intentionally as the product evolves.
  10. Document for use, not archival. Documentation must answer when to use a pattern, when not to use it, how it behaves, how it is implemented, and who owns it.

See references/principle-cards.md for each principle as a reusable card.

Default recommendations

Use these defaults unless the user provides context that clearly calls for a different choice.

Product and scope defaults

  • Default scope: define the smallest useful system slice: tokens + 3-5 core components + 1-2 representative templates + documentation. This avoids a bloated “big bang” system.
  • Default prioritization: prioritize high-frequency, high-risk patterns first: buttons, links, forms, alerts, navigation, cards/lists, layout primitives, type scale, spacing, color semantics, loading/empty/error states.
  • Default migration: improve incrementally. Prefer component-by-component replacement and deprecation over a full redesign unless the product is early-stage or a major platform migration is already happening.

Design-system structure defaults

  • Default model: use a layered system: foundations/tokens → primitives → components → compositions/templates → product examples/pages.
  • Default naming: name patterns by purpose, not appearance. Prefer Primary action, Course card, Filter panel, Inline validation, or Promotion banner over blue button, big box, or right rail thing.
  • Default documentation: every reusable pattern gets purpose, anatomy, variants, states, accessibility contract, content guidance, responsive behavior, implementation notes, examples, and anti-examples.
  • Default governance: use light curation. Allow contribution, but require review for new tokens/components and require evidence before adding variants.

Token defaults

  • Default token categories: color, typography, spacing, radius, border, elevation/shadow, motion, opacity, z-index/layer, size, breakpoint/container, and semantic state tokens.
  • Default token shape: separate primitive values from semantic tokens. Example: primitive color.blue.600; semantic color.action.primary.bg; component token button.primary.bg only when component-specific mapping is necessary.
  • Default naming: use role and state rather than raw appearance. Prefer text.muted, surface.raised, border.focus, status.error.fg over gray-500-for-labels.
  • Default override rule: do not introduce a new token for a single exception. First test whether an existing semantic token, component variant, or local product need already covers the case.

Layout and responsive defaults

  • Default layout strategy: design content-first, intrinsically responsive layouts using flexible containers, grid/flex primitives, fluid spacing, and container-aware rules. Avoid designing separate desktop/tablet/mobile screens as unrelated artifacts.
  • Default breakpoints: use only enough breakpoints to protect readability, navigation, and task completion. Prefer component/container behavior over global viewport choreography.
  • Default density: start with moderate density and generous scanability. Increase density only when expert workflows, data-heavy tasks, or screen real estate constraints justify it.
  • Default content testing: test with real or realistic content, including long labels, missing images, empty data, error states, loading states, dense data, and translated strings when relevant.

CSS and frontend defaults

  • Default markup: semantic HTML first. Add ARIA only to fill semantic gaps, not to replace native semantics.
  • Default CSS: component-scoped, low-specificity, token-driven CSS. Avoid styling through deep page location selectors.
  • Default methodology: pick or adapt a clear naming and layering convention. BEM-like naming, utility layers, CSS modules, or framework-scoped styles can all work if the rules are explicit and consistent.
  • Default JS: do not use JavaScript for effects CSS handles reliably. Use JS when behavior, state, data, or accessibility requires it.
  • Default custom controls: start with native controls. If custom styling is needed, preserve native semantics, labels, keyboard behavior, focus visibility, and form behavior.
  • Default build/process: automate linting, formatting, type checks where applicable, accessibility checks, visual regression for important components, and preview/documentation builds.

Accessibility defaults

  • Default target: meet WCAG 2.2 AA expectations unless the user has a stricter internal standard.
  • Default contrast: text and meaningful UI indicators must meet contrast requirements; do not rely on color alone for state.
  • Default focus: all interactive controls need visible focus and keyboard operation.
  • Default targets: small controls need usable hit areas, especially for touch and motor accessibility.
  • Default motion: motion should be purposeful, brief, interruptible when possible, and honor reduced-motion preferences.

Required user questions

Ask only when the answer materially changes the system. Do not ask users to decide routine best practices.

Ask a focused question when any of these are unknown and relevant:

  • The product goal, user task, or target audience is unclear.
  • The user asks for a new system, but the brand/product personality or existing system maturity is unknown.
  • The work must integrate with an existing frontend stack, CMS, component framework, or token format.
  • The product has unusual accessibility, regulatory, performance, device, localization, or data-density constraints.
  • The user wants a recommendation that depends on governance, team size, release process, or contribution model.
  • The user asks to override a default that would affect accessibility, implementation cost, brand consistency, or maintainability.

When asking, include a recommended default and options. Use a question tool or equivalent pattern when available.

Use the question-tool-ready prompts in references/decision-prompts.md.

Workflow: critique existing work

When reviewing an existing UI, design system, component library, or frontend implementation, inspect in this order:

  1. Task fit and product purpose — What user goal is the UI solving? Are the main actions and outcomes clear?
  2. System coverage — What tokens, components, templates, and states already exist? What is duplicated or missing?
  3. Information hierarchy — Are primary, secondary, and tertiary elements distinguishable without decorative overuse?
  4. Functional patterns — Are modules named, purposeful, reusable, and behaviorally clear?
  5. Perceptual patterns — Are color, type, spacing, motion, imagery, and tone consistent with the intended personality?
  6. Layout and responsiveness — Does the layout adapt from content and container needs rather than arbitrary breakpoints?
  7. Interaction clarity — Are affordances, states, validation, loading, errors, empty states, and edge cases specified?
  8. Accessibility — Check semantics, keyboard flow, focus, contrast, labels, target size, reading order, motion, and assistive text.
  9. Frontend feasibility — Inspect markup complexity, CSS specificity, token mapping, dependencies, performance risk, and testability.
  10. Documentation and governance — Is there a source of truth, ownership, contribution path, and deprecation process?

Output critiques as: highest-risk issue → why it matters → recommended fix → system implication → implementation note. Avoid long unordered lists of visual opinions.

Workflow: create or improve a system

When creating a new recommendation, proceed in this order:

  1. Clarify the feature or user problem. Identify the main task, audience, platform, existing constraints, and success criteria.
  2. Choose the smallest useful system slice. Do not start with an exhaustive component catalog.
  3. Inventory existing patterns. Look for repeated functions, repeated styles, duplicated code, inconsistent names, and recurring states.
  4. Define functional patterns. Group UI by purpose and behavior, then name components by what they do.
  5. Define perceptual patterns. Extract the product’s signature treatments: type, color, spacing, shape, motion, imagery, tone, and state expression.
  6. Establish tokens. Convert recurring perceptual decisions into primitive, semantic, and component-level tokens where useful.
  7. Specify component contracts. For each component, document anatomy, variants, states, content rules, accessibility behavior, responsive behavior, and implementation guidance.
  8. Compose templates with real content. Validate components in actual flows and page-level compositions.
  9. Plan implementation architecture. Choose semantic markup, CSS strategy, component boundaries, build/test pipeline, distribution, and migration path.
  10. Document and govern. Define ownership, contribution, review, release, deprecation, and adoption workflow.
  11. Validate. Run quality, accessibility, responsive, performance, and maintainability checks before finalizing.
  12. Explain decisions. Tie recommendations to user goals, system consistency, accessibility, maintainability, and implementation cost.

Decision framework

Use this sequence before recommending a pattern or architecture:

  1. Purpose: What problem or user task does this solve?
  2. Reuse: Will this recur across features, products, or states?
  3. Variation: What variants are truly needed, and what variants are accidental one-offs?
  4. Content: What content types, lengths, states, and localization cases must the pattern survive?
  5. Accessibility: What semantics, focus behavior, keyboard interaction, labels, contrast, target size, and motion rules are required?
  6. Implementation: Can it be implemented with semantic markup, low-specificity CSS, tokens, and minimal JS?
  7. System fit: Does it align with existing tokens, components, names, and documentation?
  8. Governance: Who owns it, how does it change, and how will users know which version to use?

Recommend the lowest-complexity solution that satisfies these constraints. Add complexity only when the product context justifies it.

Practical rules

Component rules

  • A component must have a purpose, not just a visual shape.
  • Do not create a component from a screenshot alone. First identify user task, content model, states, and responsive behavior.
  • Prefer fewer components with well-defined variants over many near-duplicates.
  • A variant must represent a meaningful difference in purpose, prominence, state, or context.
  • Components should expose stable APIs or props that map to system decisions, not arbitrary styling escape hatches.
  • Every component needs examples with realistic content and at least one edge case.

Token rules

  • Tokens should express decisions, not merely store values.
  • Use semantic tokens for meaning and primitive tokens for palette/scale management.
  • Do not let product teams consume raw primitives directly when a semantic decision is available.
  • Do not solve one-off needs by expanding the token set before checking whether the need is recurring.
  • Include state tokens for hover, active, focus, disabled, selected, success, warning, error, and loading where applicable.

Documentation rules

  • Document usage rules before implementation trivia.
  • Include “Use when” and “Do not use when” for every major pattern.
  • Include visual examples and anti-examples when they prevent misuse.
  • Keep documentation close enough to code or design source-of-truth that it does not drift.
  • Treat names and glossary entries as part of the product architecture.

Governance rules

  • Require a reason for new patterns: missing user need, repeated product need, accessibility requirement, or implementation simplification.
  • Require review before new visual styles, component variants, or tokens are added.
  • Allow experiments outside the core system, but define when an experiment graduates, changes, or dies.
  • Track deprecated components and provide migration guidance.
  • Measure system health by adoption, duplication reduction, accessibility quality, delivery speed, and user-facing consistency.

Accessibility and inclusion requirements

For each component or UI recommendation, specify:

  • Semantic element choice and accessible name.
  • Keyboard interaction and tab order.
  • Focus, hover, active, selected, disabled, invalid, loading, success, and error states.
  • Contrast and non-color state indicators.
  • Touch/motor target size and spacing between controls.
  • Screen reader behavior, live regions, and error announcements where relevant.
  • Reduced-motion alternative for decorative or transition-heavy behavior.
  • Text resizing and zoom resilience.
  • Localization and content expansion risk when relevant.
  • Inclusive defaults for reading order, language clarity, and non-punitive error copy.

Never recommend custom controls unless you also specify how the native semantics and interactions are preserved.

Frontend implementation guidance

Semantic HTML

  • Start from the native element that already carries the needed behavior: button, a, input, select, textarea, details, dialog, list elements, headings, landmarks, and table elements where appropriate.
  • Use headings and landmarks to preserve meaningful page structure.
  • Use ARIA only when native semantics are insufficient, and keep ARIA state synchronized with actual UI state.

Component structure

  • Keep component responsibilities small and explicit.
  • Separate container/data orchestration from presentational primitives when it improves reuse and testing.
  • Use composition for complex organisms and templates; avoid giant monolithic components.
  • Define inputs/props in terms of role, state, and content, not raw CSS.
  • Include empty, loading, error, success, disabled, selected, and overflow cases in the component contract.

CSS and layout

  • Use tokens for recurring values.
  • Keep specificity low; avoid deeply nested selectors and page-location dependencies.
  • Prefer layout primitives and component-contained responsive rules over scattered page-level overrides.
  • Use modern layout tools such as flex and grid when supported by the project constraints.
  • Use CSS for presentation, transitions, and state styling when CSS can handle the behavior accessibly and reliably.
  • Avoid !important except for intentional utility layers or known override boundaries.

Responsive behavior

  • Define how content reflows, truncates, wraps, stacks, or collapses.
  • Test components independently and inside representative templates.
  • Avoid assuming fixed dimensions unless the content and platform truly enforce them.
  • Treat narrow viewports, high zoom, and large text as first-class cases.

Performance and maintainability

  • Avoid shipping duplicate component implementations.
  • Avoid large dependency additions for small presentational problems.
  • Use build tools to automate repeatable tasks, but do not choose tools for novelty alone.
  • Add visual regression tests to high-value components and templates where UI drift would be costly.
  • Include migration notes when changing a component API, token name, or markup structure.

Quality checklist

Before finalizing work, verify:

  • The recommendation is scoped by components, states, and content, not only by pages.
  • The primary user task and success criteria are clear.
  • Functional and perceptual patterns are both addressed.
  • Tokens distinguish primitive values from semantic decisions.
  • Components have purpose, anatomy, variants, states, accessibility, responsive behavior, and implementation notes.
  • Layout is resilient to content changes and viewport/container changes.
  • Accessibility is treated as a requirement, not an afterthought.
  • The CSS strategy avoids specificity escalation and one-off overrides.
  • Documentation explains when and why to use patterns.
  • Governance explains how the system evolves without becoming bloated or stale.
  • Tradeoffs are explained in product, user, and implementation terms.

Use the full checklists in references/checklists.md.

Common mistakes to avoid

  • Estimating or planning by page count instead of component/functionality complexity.
  • Creating a “component library” that is only a gallery of screenshots or disconnected modules.
  • Naming components by appearance rather than purpose.
  • Creating tokens that merely mirror raw CSS values without semantic meaning.
  • Treating color, type, motion, spacing, and tone as superficial decoration rather than perceptual patterns.
  • Enforcing perfect consistency so strictly that product character and useful experimentation disappear.
  • Allowing unlimited variants and one-off overrides until the system becomes incoherent.
  • Building custom controls without preserving native behavior and accessibility.
  • Solving layout with brittle fixed dimensions and breakpoint-specific hacks.
  • Using JavaScript for styling effects CSS can solve more simply.
  • Letting documentation drift away from code and design source files.
  • Asking the user about routine best practices instead of applying strong defaults.

See references/anti-patterns.md for the full anti-pattern list.

How to explain recommendations to the user

Explain choices in this order:

  1. User impact: how the recommendation improves task completion, clarity, accessibility, or confidence.
  2. System impact: how it improves consistency, reuse, governance, or naming.
  3. Frontend impact: how it reduces complexity, specificity, drift, regressions, or maintenance cost.
  4. Tradeoff: what is lost or constrained, and when a different choice would be better.
  5. Next action: what to implement, document, test, or ask next.

Use concrete language. Prefer “Use one Inline validation component with success, warning, and error variants” over “make validation consistent.”

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.