feat: add Iconography section to the DESIGN.md spec

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
 

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'` |

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

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"
 

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'` |