Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

docs(design): define iconography guidance (#6429)

Ernest4a66200efde9
diff --git a/docs/design/README.md b/docs/design/README.md
index 9377467420..ac205309b4 100644
--- a/docs/design/README.md
+++ b/docs/design/README.md
@@ -24,6 +24,7 @@ state-taxonomy records:
| [Shape relationships](shape-relationships.md) | Role-based and concentric geometry for nested surfaces |
| [Elevation hierarchy](elevation-hierarchy.md) | Agreement between perceived depth and actual layer order |
| [Typography hierarchy](typography-hierarchy.md) | Legible, distinguishable text roles across themes and layouts |
+| [Iconography](iconography.md) | Icon meaning, size, artwork, color, composition, and accessibility |
| [Color emphasis](color-emphasis.md) | Semantic color roles, contrast intent, and local emphasis |
| [Motion](motion.md) | Meaningful movement, timing hierarchy, easing intent, and reduced motion |
| [Ordered collection reordering](ordered-collection-reordering.md) | Drag preview, candidate insertion, commit, and settle intent for ordered collections |
diff --git a/docs/design/iconography.md b/docs/design/iconography.md
new file mode 100644
index 0000000000..97eb588f21
--- /dev/null
+++ b/docs/design/iconography.md
@@ -0,0 +1,371 @@
+---
+schema_version: 1
+template_version: 1
+kind: design
+id: design:iconography
+authority: draft
+archive_reason: null
+superseded_by: null
+approved_by: null
+approved_at: null
+owners: [ernestt, cixzhang]
+review_triggers: [visual, interaction, theming, accessibility]
+verified_by: []
+architecture:
+ [
+ architecture:component-theming-surface,
+ architecture:icon-resolution-and-component-slots,
+ architecture:theme-authoring-contract,
+ ]
+components: [component:Icon, component:Table]
+families: []
+deciding_specs: []
+---
+
+# Iconography design specification
+
+## User intent
+
+Icons are simple graphic interface elements that represent common actions,
+concepts, and states. They should help people understand a surface, complete a
+task, and find their way without adding visual noise or forcing them to decode
+inconsistent symbols.
+
+## Design principles
+
+- **DR1 — Clear.** Icons MUST use simple, recognizable forms that communicate
+ their intended meaning and aid comprehension.
+- **DR2 — Intentional.** Every icon MUST have a purposeful role in its local
+ context. Designers SHOULD evaluate the whole container and page before adding
+ another icon so decoration does not increase cognitive load.
+- **DR3 — Consistent.** Repeated concepts, actions, geometry, size roles, and
+ artwork styles SHOULD remain coherent across the product. Components SHOULD
+ reuse system semantic icons instead of introducing bespoke symbols for an
+ existing meaning.
+- **DR4 — Size follows semantic role.** A glyph MUST be sized for what it does,
+ not merely for the nearest available space or the intrinsic proportions of its
+ artwork.
+- **DR5 — Outlined artwork is the default.** When an icon family offers outlined
+ and filled versions of the same symbol, components SHOULD start with the
+ outlined version unless a permitted filled use applies.
+- **DR6 — Color supports meaning.** Icon color MUST follow an approved foreground,
+ semantic, or constrained non-semantic role. Color alone MUST NOT communicate a
+ concept or state.
+- **DR7 — Glyph and target are separate.** Icon artwork MUST NOT be used as a
+ substitute for an interactive container, operable hit target, focus treatment,
+ or accessible name.
+
+## Anatomy and hierarchy
+
+### Meaning roles
+
+| Role | Purpose | Required relationship |
+| ------------------- | ---------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| informative icon | Adds information or meaning beyond an adjacent label | May stand alone only with an accessible name and enough explanation to understand it |
+| decorative icon | Reinforces nearby text without adding independent meaning | MUST accompany content that already communicates the meaning; normally uses outlined artwork |
+| interactive icon | Represents an action inside an interactive control | The containing Button, IconButton, link, or other control owns interaction, state, focus, name, and target |
+| semantic icon | Reinforces information, success, warning, or error meaning | Uses the matching semantic icon and color together; the meaning remains available independently of color |
+| object or logo icon | Identifies a specific object, product, or brand | Used only when recognition of that object is relevant; not as generic decoration for a category or section |
+
+### Size roles
+
+Astryx exposes four Icon sizes. Values are px-equivalents at a 16px root; Icon
+continues to scale with the document's root font size.
+
+| Role | Current Icon size | Purpose and current relationship |
+| ----------------- | ----------------- | --------------------------------------------------------------------------------- |
+| compact indicator | 12px (`xsm`) | Supporting indicators, metadata, and dense affordances |
+| standard control | 16px (`sm`) | Most controls and disclosure affordances; current Button `sm` and `md` icon boxes |
+| prominent control | 20px (`md`) | Large controls and visually important icon-only actions; current Button `lg` box |
+| display or object | 24px (`lg`) | Large standalone symbols, object identity, or exceptional display-scale treatment |
+
+These roles describe visual intent, not new public Icon size names. Component
+contracts own their role assignment. Bare Icon currently defaults to `md` (20px),
+while many composing controls explicitly constrain their icon slot to 16px or
+20px. An open contextual-sizing change may make an omitted Icon size inherit from
+its owning control; this record does not depend on that implementation landing.
+
+### Outlined and filled artwork
+
+Outlined artwork is the starting point. Filled artwork MAY be used when one or
+more of these conditions applies:
+
+1. The icon also conveys an active or on state, such as a toggle or selected
+ navigation item.
+2. The icon is 12px-equivalent or smaller and fill demonstrably improves
+ recognition.
+3. An informational icon carries a persistent semantic color, such as information,
+ success, warning, or error status.
+4. The icon intentionally needs higher emphasis, such as a primary action or
+ object identity.
+5. The icon appears on media or another visually busy background and fill improves
+ contrast or recognition.
+6. The icon is a logo or brand mark whose canonical artwork is filled.
+
+The shape of a symbol or a secondary foreground color is not enough by itself to
+require fill. Astryx's current fallback chevrons, close mark, search icon, and sort
+arrows are outlined at every size, while status icons are filled and intrinsically
+solid marks such as more and stop remain solid. Peer controls SHOULD use a cohesive
+artwork language, but cohesion does not override their semantic roles.
+
+A filled exception MUST remain purposeful and local. It does not make filled
+artwork the global default. Intrinsically solid primitives with no meaningful
+outlined counterpart are not treated as filled variants merely because they
+contain a solid shape.
+
+## State representation
+
+| State or context | Required representation | Allowed variation |
+| ------------------------ | ------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------- |
+| rest | Uses the role's normal size, color, and outlined artwork unless a filled exception applies | Theme artwork and optical adjustment may vary |
+| active or on | May change from outlined to filled while preserving one recognizable symbol | Another established non-fill state treatment may reinforce the state |
+| compact indicator | Remains subordinate and recognizable; fill is allowed at 12px or smaller when it helps | Size-specific artwork may improve legibility |
+| semantic status | Pairs the status icon with its matching semantic color and accessible meaning | Filled artwork may provide persistent emphasis |
+| disabled | Uses the approved disabled foreground without losing recognition | Artwork stays consistent with the role |
+| on media or busy surface | Retains contrast and recognition against variable content | Filled artwork and an inherited high-contrast foreground may be used |
+| alternate theme | Meaning, role hierarchy, and outlined/filled intent remain recognizable | Icon library and exact artwork may differ; role-specific sizing needs an exposed target |
+
+An outlined-to-filled change MUST NOT be the only cue for a state whose
+distinction must remain perceivable. Programmatic state, accessible naming,
+position, color, or another established treatment must continue to carry it.
+
+## Color roles
+
+Astryx Icon currently exposes `primary`, `secondary`, `tertiary`, `disabled`,
+`accent`, `success`, `warning`, `error`, and `inherit`, plus named palette colors.
+The design intent is:
+
+- **Primary** carries ordinary high-emphasis icon content.
+- **Secondary and tertiary** carry supporting icon content. Their current token
+ mapping may coincide, but the semantic role remains distinct.
+- **Disabled** communicates unavailable icon content without implying status.
+- **Accent** communicates selected emphasis or information when the owning
+ component assigns that meaning.
+- **Success, warning, and error** are reserved for matching semantic outcomes.
+- **Inherit** lets the owning control or surface provide the correct foreground,
+ including media and other busy surfaces.
+- **Named palette colors** do not acquire semantic meaning from Icon. Use them only
+ when an owning component or product defines and consistently applies a
+ non-semantic category mapping.
+
+`placeholder` and `onMedia` are not current Icon color values. A component may
+create those visual roles through inheritance or a qualified theme target, but
+this design record does not invent new Icon API values.
+
+## Responsive and input behavior
+
+- **DR8 — Density does not erase meaning.** A dense layout MAY choose the compact
+ role for supporting indicators, but primary controls MUST remain recognizable
+ as controls.
+- **DR9 — Input adaptation belongs to the target.** Touch or coarse-pointer modes
+ MAY increase the containing target or spacing without changing the glyph when
+ its semantic role is unchanged.
+- **DR10 — Role changes are explicit.** Responsive composition MUST NOT silently
+ move an icon among compact, standard-control, prominent-control, and display
+ roles solely to make it fit; the component or family contract must establish
+ that variation.
+- **DR11 — Compact artwork preserves recognition.** At 12px-equivalent or smaller,
+ a theme MAY choose filled or otherwise optically simplified artwork when an
+ outlined asset loses clarity. A 16px icon does not become filled merely because
+ it is small; one of the filled-use criteria must still apply. The symbol's
+ meaning and surrounding layout must remain unchanged.
+
+## Composition guidance
+
+### Icons in controls
+
+- An interactive icon MUST be placed in an IconButton, Button, link, or another
+ control that supplies interaction states, focus, an accessible name, and an
+ adequate target.
+- A bare Icon MUST NOT become interactive by attaching a click handler without an
+ owning control.
+
+### Icons in tabs
+
+- A leading tab icon MAY identify a destination or reinforce the visible label.
+ Decorative icons SHOULD be omitted when they add distraction or width without
+ useful recognition.
+- A selected icon MAY change to reinforce the selected state when the label and
+ tab semantics continue to carry that state.
+- Status icons, badges, and status dots belong in the tab's end-content or status
+ position rather than replacing the tab label.
+
+### Icons in tokens and badges
+
+- Informational status treatment pairs the semantic icon and color so the
+ combination communicates status without arbitrarily recoloring the container.
+- A token or badge MAY coordinate its surface and icon through a component-owned
+ semantic variant; a nested icon alone does not redefine the container's meaning.
+
+### Icons in links
+
+- Links SHOULD primarily use text. An icon MAY supplement that text when it adds
+ a useful visual cue.
+- An icon-only link MAY be used when the destination is recognizable in context
+ and the Link receives a non-empty accessible `label`. Prefer Button with `href`
+ when the interaction should read as a control rather than inline navigation.
+
+### Icons in lists
+
+- Non-selectable description and menu lists SHOULD normally use outlined icons at
+ the standard 16px-equivalent size and a supported foreground role.
+- Filled artwork, compact sizing, or named palette color MAY be used when another
+ rule in this record applies; decoration alone is not sufficient justification
+ for added emphasis.
+
+### Icons in headers
+
+- A header MAY include object media when the heading identifies a specific object
+ and the icon materially aids recognition.
+- Most category and section headings SHOULD NOT include an icon; generic media
+ adds noise without clarifying the section.
+
+### Icons in navigation
+
+- Navigation icons MUST be chosen intentionally: use a clear, simple symbol that
+ represents the destination rather than a generic decorative mark.
+- Selected navigation MAY use a component-owned outlined-to-filled pair when text,
+ `aria-current`, or another established treatment continues to identify selection.
+
+## Accessibility intent
+
+- Informative icons need an accessible image name when the information is not
+ already available in text. Explanatory text or a tooltip should be available
+ when the symbol alone may be ambiguous.
+- Decorative icons expose no duplicate name and remain paired with visible text
+ that communicates the meaning.
+- Icon artwork MUST remain recognizable at its rendered size. Astryx does not
+ require every icon at 16px or below to be filled: current fallbacks are mostly
+ outlined, with filled status icons and intrinsically solid marks. Prefer
+ size-specific or optically adjusted artwork when available; use fill only when
+ a filled-use criterion above applies.
+- Icon foregrounds MUST maintain applicable contrast against their backgrounds.
+- Interactive icons need adequate surrounding space for recognition and an
+ operable target owned by their control.
+
+## Representative examples
+
+- A grouped-row disclosure chevron is an interactive control for an entire
+ section, so its intended standard role is 16px-equivalent rather than a 12px
+ supporting indicator. Astryx's current fallback chevron remains outlined.
+- A table sort-direction arrow is a compact indicator associated with a column
+ heading, so it uses the 12px-equivalent role while the button and `aria-sort`
+ carry interaction and state. It does not require filled artwork.
+- A persistent semantic information cue may use filled artwork and the accent
+ color when nearby content or an accessible name explains it.
+- An on/off control may pair outlined artwork for off with the corresponding
+ filled artwork for on while its semantic state remains available independently.
+- A large icon-only Button uses a 20px-equivalent prominent-control glyph when the
+ containing target and spacing support it; icon-only does not automatically mean
+ prominent.
+- A 24px-equivalent icon is reserved for display-scale or object treatment rather
+ than the default icon-button glyph.
+- A non-selectable list item normally uses a standard-size outlined icon in a
+ primary or secondary foreground.
+
+## Visual references
+
+No normative assets are included. Public-safe examples of meaning roles, the
+12/16/20/24 size ladder, outlined/filled exceptions, color roles, and
+representative compositions should be added under
+`docs/design/assets/iconography/` before promotion.
+
+## Component contract links
+
+- `component:Icon` owns the shared 12/16/20/24 size vocabulary, bare-Icon
+ `md` default, scaling behavior, target, color API, and rendering semantics; this
+ record assigns design intent to role, color, and artwork selection.
+- Interactive components own their target, state, focus, accessible name, and icon
+ slot geometry; Icon remains the glyph inside that owner.
+- `component:Table` owns which generated Table affordances are compact indicators
+ or standard controls. Grouped-row disclosure is the first candidate for an
+ explicit standard-control link after this record becomes current.
+- `architecture:icon-resolution-and-component-slots` owns semantic-name and
+ artwork resolution. A component selects placement, size, color, and state before
+ the registry supplies artwork; the registry is not the owner of those roles.
+- `architecture:component-theming-surface` owns theming guarantees. The shared
+ Icon target reflects `size` and `color`, so themes may coherently style existing
+ values. A local component-role override still requires a qualified owning target
+ with the relevant property guarantee; this record does not create one.
+
+## Decision log
+
+### DEC-1 — Outlined artwork is the default with deliberate filled exceptions
+
+**Reference:** `design:iconography/DEC-1`
+**Decider:** pending design-owner approval
+
+Start with outlined artwork when a meaningful pair exists. Use the filled
+counterpart only for active state, verified compact recognition at 12px or smaller,
+persistent semantic status, deliberate emphasis, busy backgrounds, or canonical
+logos. Maintain cohesion among peer controls without treating a symbol's shape or
+secondary color as automatic permission to fill it.
+
+Rejected: using filled artwork as the universal default, filling every icon at
+16px or below, filling chevrons and close marks categorically, using fill as the
+sole state cue, or selecting fill simply because the asset exists.
+
+### DEC-2 — Astryx uses a 12 / 16 / 20 / 24 role ladder
+
+**Reference:** `design:iconography/DEC-2`
+**Decider:** pending design-owner approval
+
+Use 12px-equivalent for compact supporting indicators, 16px-equivalent for
+standard controls and disclosures, 20px-equivalent for prominent controls such as
+large icon buttons, and 24px-equivalent for display-scale or object treatment.
+Bare Icon currently defaults to 20px-equivalent `md`; composing components may
+constrain their icon slots independently.
+
+Rejected: importing the older three-size 12/16/24 profile unchanged, calling 16px
+the primitive Icon default, using one size for every icon, or selecting size from
+available space without regard to meaning.
+
+### DEC-3 — Informative and decorative icons have different content obligations
+
+**Reference:** `design:iconography/DEC-3`
+**Decider:** pending design-owner approval
+
+An informative icon may carry meaning beyond its label and therefore needs an
+accessible name and enough explanation when used independently. A decorative icon
+adds no independent meaning, stays paired with text, and is hidden from assistive
+technology to avoid duplicate announcements.
+
+Rejected: treating every icon as informative, or allowing a decorative icon to
+stand alone without a label.
+
+### DEC-4 — Themes tune shared and component roles at their owning surface
+
+**Reference:** `design:iconography/DEC-4`
+**Decider:** pending design-owner approval
+
+A theme may replace artwork for a shared semantic icon name and may coherently
+tune an existing `Icon.size` value through the shared Icon target. A local role
+such as one component's disclosure control should instead use a qualified
+component-owned target when that target exists and guarantees the relevant
+property. Components continue to own placement, state, and accessible semantics;
+this record creates no new target or guarantee.
+
+Rejected: adding ad hoc size names, changing a shared size solely to affect one
+component, using the artwork registry as the owner of component behavior or state,
+or assuming every icon-bearing role is independently themeable today.
+
+## Open questions
+
+- **OQ1 — Theme-target rollout.** Which existing component roles need dedicated
+ qualified targets for theme authors to tune size, color, or artwork
+ independently?
+- **OQ2 — Current conformance.** Which shipped callsites differ from the current
+ 12/16/20/24 role ladder, outlined default, or composition guidance and need an
+ explicit component-owned exception?
+- **OQ3 — Normative evidence.** Which public-safe examples best demonstrate the
+ meaning roles, size and artwork rules, colors, and composition across the
+ reference system theme and a deliberately different theme personality?
+
+## Content boundary
+
+This file defines public visual, composition, and accessibility intent for
+iconography. It does not prescribe a particular icon library, asset-management
+workflow, request process, implementation framework, prop syntax, target selector,
+registry descriptor, or migration tooling. It does not change Icon's released
+size vocabulary or default, define hit-target thresholds, choose individual SVG
+geometry, or implement theme overrides.