diff --git a/README.md b/README.md index 055c98c8..95e5d549 100644 --- a/README.md +++ b/README.md @@ -139,8 +139,9 @@ Sections use `##` headings. They can be omitted, but those present must appear i | 4 | Layout | Layout & Spacing | | 5 | Elevation & Depth | Elevation | | 6 | Shapes | | -| 7 | Components | | -| 8 | Do's and Don'ts | | +| 7 | Iconography | | +| 8 | Components | | +| 9 | Do's and Don'ts | | ### Component Tokens diff --git a/docs/spec.md b/docs/spec.md index 41b6d085..16d9b43a 100644 --- a/docs/spec.md +++ b/docs/spec.md @@ -97,8 +97,9 @@ Every `DESIGN.md` follows the same structure. Sections can be omitted if they're 4. **Layout** (also: "Layout & Spacing") 5. **Elevation & Depth** (also: "Elevation") 6. **Shapes** -7. **Components** -8. **Do's and Don'ts** +7. **Iconography** +8. **Components** +9. **Do's and Don'ts** ### Prose and Tokens @@ -284,6 +285,25 @@ rounded: full: 9999px ``` +## Iconography + +This section describes how icons support the visual language. It should name the +icon library or custom system and explain why it fits the product, then define +the style variant, stroke or weight conventions, sizing scale, color rules, and +whether multiple icon sets may be mixed. + +Example: + +```markdown +## Iconography + +Use Heroicons for its broad coverage and crisp UI semantics. Icons are outlined +by default with a 1.5px stroke; filled variants are reserved for selected or +high-emphasis states. Sizes follow 16px, 20px, and 24px steps, inherit text color +in controls, and use semantic color only for status. Do not mix icon sets unless +a missing symbol is redrawn to match the same stroke, corner, and optical size. +``` + ## Components This section provides style guidance for component atoms within the design system. The following are common component types. Design systems are encouraged to define additional components relevant to their domain. @@ -357,7 +377,7 @@ When a DESIGN.md consumer encounters content not defined by this spec: | Scenario | Behavior | Example | |---|---|---| -| Unknown section heading | Preserve; do not error | `## Iconography` | +| Unknown section heading | Preserve; do not error | `## Motion` | | Unknown color token name | Accept if value is valid | `surface-container-high: '#ede7dd'` | | Unknown typography token name | Accept as valid typography | `telemetry-data` | | Unknown spacing value | Accept; store as string if not a valid dimension | `grid-columns: '5'` | diff --git a/examples/paws-and-paths/DESIGN.md b/examples/paws-and-paths/DESIGN.md index 72b25afa..b10bd7a2 100644 --- a/examples/paws-and-paths/DESIGN.md +++ b/examples/paws-and-paths/DESIGN.md @@ -204,6 +204,13 @@ The shape language is defined by **Rounded** corners, mirroring the soft feature - **Inputs:** Form fields use a `0.5rem` radius to maintain a professional yet modern appearance. - **Icons:** Icons should feature rounded caps and corners to harmonize with the UI's structural elements. +## Iconography + +Paws and Paths uses Lucide icons because the rounded outline style fits the friendly, service-focused brand. +Prefer outlined symbols with 2px strokes and rounded caps; reserve filled icons for active navigation or important pet status. +Sizes step from 16px for metadata to 24px for primary actions, and icons inherit text color unless a semantic orange, blue, or error state is needed. +Do not mix icon libraries unless the replacement is redrawn to match the same stroke, corners, and visual weight. + ## Components ### Buttons & Inputs diff --git a/packages/cli/src/linter/spec-config.yaml b/packages/cli/src/linter/spec-config.yaml index 67dfa143..9c424a3a 100644 --- a/packages/cli/src/linter/spec-config.yaml +++ b/packages/cli/src/linter/spec-config.yaml @@ -41,6 +41,7 @@ sections: aliases: - Elevation - canonical: Shapes + - canonical: Iconography - canonical: Components - canonical: "Do's and Don'ts" diff --git a/packages/cli/src/linter/spec-gen/spec.mdx b/packages/cli/src/linter/spec-gen/spec.mdx index 44064d5c..5326cd08 100644 --- a/packages/cli/src/linter/spec-gen/spec.mdx +++ b/packages/cli/src/linter/spec-gen/spec.mdx @@ -228,6 +228,25 @@ rounded: full: 9999px ``` +## Iconography + +This section describes how icons support the visual language. It should name the +icon library or custom system and explain why it fits the product, then define +the style variant, stroke or weight conventions, sizing scale, color rules, and +whether multiple icon sets may be mixed. + +Example: + +```markdown +## Iconography + +Use Heroicons for its broad coverage and crisp UI semantics. Icons are outlined +by default with a 1.5px stroke; filled variants are reserved for selected or +high-emphasis states. Sizes follow 16px, 20px, and 24px steps, inherit text color +in controls, and use semantic color only for status. Do not mix icon sets unless +a missing symbol is redrawn to match the same stroke, corner, and optical size. +``` + ## Components This section provides style guidance for component atoms within the design system. The following are common component types. Design systems are encouraged to define additional components relevant to their domain. @@ -281,7 +300,7 @@ When a DESIGN.md consumer encounters content not defined by this spec: | Scenario | Behavior | Example | |---|---|---| -| Unknown section heading | Preserve; do not error | `## Iconography` | +| Unknown section heading | Preserve; do not error | `## Motion` | | Unknown color token name | Accept if value is valid | `surface-container-high: '#ede7dd'` | | Unknown typography token name | Accept as valid typography | `telemetry-data` | | Unknown spacing value | Accept; store as string if not a valid dimension | `grid-columns: '5'` |