spec: Iconography section

[davideast]

Status: Exploring

Background

@dovas-net proposed adding iconography to the spec in #41, and built a full implementation in PR #44. @AndrewOCC contributed ideas around end-cap style, line-join style, and linking to external icon library metadata. That work and discussion is the foundation for this issue.

After thinking through #41 alongside several other token proposals (#47, #49, #65), I wrote up the project's philosophy on how the spec evolves in PHILOSOPHY.md. The short version: the spec defines universal categories and the prose is where the design lives. Tokens are non-normative reference points, not rendering instructions.

Direction

Iconography is a universal enough category that it belongs in the spec as a recognized section. Nearly every design system has icon conventions worth documenting.

What this means:

• An ## Iconography section is added to the spec's canonical section order
• The section is prose-focused, like Colors, Typography, and every other section
• Any tokens are non-normative examples, not required fields
• The linter recognizes the section but does not enforce a specific token schema

What this does not mean:

• No required icons.* token group with validated fields
• No enum enforcement on style values
• No linter rules specific to icon tokens

What the section should guide authors to describe

Instead of prescribing token fields, the section should prompt authors to cover the conventions that matter for their system. Common areas include:

• Library and rationale — which icon set and why it fits the design
• Style variant — outlined, filled, duotone, etc.
• Stroke and weight conventions — stroke width, end caps, line joins
• Size scale and grid — the base grid and named scale stops
• Color rules — does icon color follow surrounding text? Use a fixed token? Vary by semantic role?
• Mixing policy — one library only, or custom icons allowed? If custom, what constraints?

These are suggestions for prose, not a schema.

Open questions

Looking for input on these:

1. Non-normative token examples. Should the spec include example tokens for reference? If so, which ones are most useful? Something like:

   icons:
     library: Lucide
     style: outlined
     strokeWidth: 1.5

   These would appear in the spec as illustrative, not required.

2. What's hard to express in prose? Are there icon conventions that genuinely benefit from structured values over prose descriptions? This would help identify where non-normative tokens add the most value.

3. Relationship to Do's and Don'ts. Rules like "don't mix icon libraries" could live in Iconography or in the Do's and Don'ts section. Is there a natural split, or should the spec offer guidance on where icon-related restrictions go?

4. Section position. The current proposal from Feature: add Iconography section and icons.* tokens #41 placed Iconography between Shapes and Components. Does that still feel right?

Progress

• Agree on section scope and position
• Draft section description for spec
• Choose non-normative token examples (if any)
• Update spec-config.yaml
• Update spec.mdx
• Regenerate docs/spec.md
• Update examples with Iconography sections