design-foundation
Style-neutral procedure for deriving a project's own design system. Walks a project from domain evidence to design principles, recorded design decisions, and a 3-layer token architecture (Primitive → Semantic ← [data-theme] → Component). Use when: establishing design principles for a new project, creating a project design guide (docs/design.md), setting up a design token system, or reviewing a project's design foundation completeness. Does NOT prescribe colors, fonts, spacing, or trends — those are project decisions.
- License 许可
- AGPL-3.0
- 最近更新
- 2026-11-14
- Stars
- ★ 25
- Forks
- 9
01 前言 Front Matter
- name
- design-foundation
- owner
- design-system-lead
- scope
- common
- status
- active
- version
- 1.1.1
- metadata
- { "type": "process", "triggers": [ "design foundation", "design principles", "design guide", "design tokens setup", "design decision record" ] }
- relates_to
- [ { "type": "enables", "skill": "ui-ux-design-intelligence" }, { "type": "composes_with", "skill": "token-usage-lint" }, { "type": "composes_with", "skill": "accessibility-audit" } ]
- description
- Style-neutral procedure for deriving a project's own design system. Walks a project from domain evidence to design principles, recorded design decisions, and a 3-layer token architecture (Primitive → Semantic ← [data-theme] → Component). Use when: establishing design principles for a new project, creating a project design guide (docs/design.md), setting up a design token system, or reviewing a project's design foundation completeness. Does NOT prescribe colors, fonts, spacing, or trends — those are project decisions.
- last_reviewed
- 1794441600000
- prerequisites
- none
03 SKILL.md 正文
🎨 Skill: design-foundation
Purpose
Derive a project-specific design system through a traceable procedure. This skill is the Procedure layer of the Design Foundation framework:
| Layer | Artifact |
|---|---|
| Specification (what to define) | docs/design-foundation.md (shipped inside a generated variant project's docs/; does not exist at workspace root) |
| Scaffold (how tokens are expressed) | docs/design-tokens.template.css |
| Procedure (this skill) | How to derive and apply |
| Project SSOT (what was chosen) | Project docs/design.md + token implementation |
Foundation ≠ Design System. Never copy values from another project (e.g. an existing design system) unless the project explicitly decides to — and then record that as a decision with rationale.
Procedure
Stage 1 — Domain Evidence
Read the project's PRD/SRS/context docs and user profiles. Produce an evidence list:
- Information density needs (expert console vs consumer app)
- Data criticality: are numbers/figures core? Do they need provenance?
- Audience and accessibility constraints (regulatory, language)
- Workflow shape: freeform vs staged processes
- Baseline viewport / device context
Stage 2 — Design Principles
From the evidence, derive 3–6 numbered principles, each with its rationale (e.g. "Expert Density — the domain requires dense but legible consoles"). Optionally add operating rules (P1–P6 style) for machine-checkable constraints.
Stage 3 — Design Decision Record
Create docs/design.md containing the design_decisions YAML block
(see docs/design-foundation.md §4). Every selection — philosophy, color system,
typography (body/heading/numeric, each value carrying the fallback stack contract),
spacing, radius, motion, iconography (backed by a registered vocabulary) — MUST carry
a rationale tracing back to a principle. No arbitrary aesthetic choices.
Provenance chain to preserve:
Domain Evidence → Design Principle → Design Decision → Token → Component
Stage 4 — Token Architecture
Copy docs/design-tokens.template.css into the project (e.g. styles/design-tokens.css) and fill
every <value> placeholder according to the decisions. Enforce the architecture:
- Primitive (
--color-*, fonts, spacing) — theme-neutral - Semantic (
--background,--border, status bg/fg/border triplets) — themed via[data-theme="<name>"](default theme on:root+ at least one alternate, typically dark) - Component (
--button-*,--card-*, …) — reference semantics only; no layer bypass - If figures are domain-critical: numeric font role with
font-variant-numeric: tabular-nums - If iconography is decided: activate the commented icon tokens
(
--icon-size/--icon-stroke/--icon-color) and maintain the project's machine-readable icon vocabulary registration
Stage 5 — Components
Build UI consuming component tokens only. Multi-encode status signals (color + icon + text);
aria-label on every icon-only control; visible :focus-visible state. Reference
components only from the declared component inventory (components.template.md);
new components enter via the design-phase gate.
Stage 6 — Validation
Run the Design Validation Contract (docs/design-foundation.md §7):
- [Required] design.md with complete
design_decisions; token implementation; default + alternate theme; bg/fg/border triplets; typography roles; icon library; icon vocabulary declared; component inventory declared; WCAG AA declared; focus state; non-color state encoding - [Consistency] no semantic-layer bypass; accessible labels on icon-only buttons; tabular numerals in numeric UI; no hard-coded values in governed components; icon tokens, where activated, resolve from the registered icon vocabulary
Use token-usage-lint where available for hardcoded-value detection, and accessibility-audit
(axe-core, WCAG 2.1 AA) for accessibility verification.
Report the validation result in the project docs/design.md (or a linked validation section)
before the design foundation is considered complete.
Boundaries
- This skill does NOT select visual values for the project — it structures how the project decides.
- For component-level design and implementation after tokens exist, hand off to
ui-ux-design-intelligence(this skillprecedesit). - Projects are autonomous: they may diverge from the reference implementation as long as the
architecture (3 layers,
[data-theme], decision record) and validation contract hold.
04 同仓库更多 Skills
i18n-layout
Text layout and encoding guidance: character encoding (UTF-8, legacy Korean code pages, BOM hazards), line endings, RTL/bidi handling, and script-specific font selection (Hangul focus). Use when: encoding is corrupted or mojibake appears, an RTL locale must render correctly, fonts must be chosen for a script, or CRLF/BOM issues surface.
i18n-layout
Text layout and encoding guidance: character encoding (UTF-8, legacy Korean code pages, BOM hazards), line endings, RTL/bidi handling, and script-specific font selection (Hangul focus). Use when: encoding is corrupted or mojibake appears, an RTL locale must render correctly, fonts must be chosen for a script, or CRLF/BOM issues surface.
i18n-layout
Text layout and encoding guidance: character encoding (UTF-8, legacy Korean code pages, BOM hazards), line endings, RTL/bidi handling, and script-specific font selection (Hangul focus). Use when: encoding is corrupted or mojibake appears, an RTL locale must render correctly, fonts must be chosen for a script, or CRLF/BOM issues surface.
i18n-layout
Text layout and encoding guidance: character encoding (UTF-8, legacy Korean code pages, BOM hazards), line endings, RTL/bidi handling, and script-specific font selection (Hangul focus). Use when: encoding is corrupted or mojibake appears, an RTL locale must render correctly, fonts must be chosen for a script, or CRLF/BOM issues surface.
i18n-layout
Text layout and encoding guidance: character encoding (UTF-8, legacy Korean code pages, BOM hazards), line endings, RTL/bidi handling, and script-specific font selection (Hangul focus). Use when: encoding is corrupted or mojibake appears, an RTL locale must render correctly, fonts must be chosen for a script, or CRLF/BOM issues surface.
i18n-layout
Text layout and encoding guidance: character encoding (UTF-8, legacy Korean code pages, BOM hazards), line endings, RTL/bidi handling, and script-specific font selection (Hangul focus). Use when: encoding is corrupted or mojibake appears, an RTL locale must render correctly, fonts must be chosen for a script, or CRLF/BOM issues surface.