An open source design system that's fully customizable and agent ready
TypeScript
docs(spec): NavIcon records its shipped contract as current (#8511)
Cindy Zhangf1b4c054344b
diff --git a/packages/core/src/NavIcon/NavIcon.spec.md b/packages/core/src/NavIcon/NavIcon.spec.mdindex 224a753496..f7afeb7e8e 100644--- a/packages/core/src/NavIcon/NavIcon.spec.md+++ b/packages/core/src/NavIcon/NavIcon.spec.md@@ -1,17 +1,22 @@---schema_version: 3-template_version: 3+template_version: 7kind: componentid: component:NavIcon-authority: draft+authority: currentarchive_reason: nullsuperseded_by: null-approved_by: null-approved_at: null+approved_by: cixzhang+approved_at: 2026-10-26owners: [cixzhang]review_triggers: [theming]verified_by:- [packages/core/src/NavIcon/NavIcon.test.tsx, scripts/check-knowledge.mjs]+ [+ packages/core/src/NavIcon/NavIcon.test.tsx,+ packages/core/src/theme/themingTargets.test.ts,+ apps/storybook/stories/NavIcon.stories.tsx,+ scripts/check-knowledge.mjs,+ ]modules: []families: []design_specs: []@@ -23,19 +28,33 @@ system_specs: []# NavIcon component contract+## Contract at a glance++| Area | Contract |+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |+| Public contract | `NavIcon` with a required `icon`; target `nav-icon`. |+| Behavior | A display-only circular accent container, one medium element size square, that shows the caller's icon. |+| End-user impact | Users see a consistent product mark in navigation headings; NavIcon adds nothing to the accessibility tree beyond the caller's icon. |+| Builder impact | None. |+| Compatibility/readiness | Records shipped behavior; no public change. |+| Review checks | Reject emitting any target besides `nav-icon`, or adding interaction semantics to the container. |+| Governing rules | `architecture:component-theming-surface`; `architecture:public-component-api`. |++This table is a review projection; the body below is authoritative.+## IntentNavIcon renders caller-supplied icon content inside a circular navigation-container. This record preserves that runtime behavior while 0.7.0 removes the-deprecated `navicon` theming alias.+container, typically as the logo of TopNavHeading or SideNavHeading. Consumer+usage lives in `NavIcon.doc.mjs`.## Compatibility and migration-- Released default preserved: `yes`; canonical `nav-icon` behavior is unchanged-- Removed alias: 0.7.0 stops emitting `navicon`+- Released default preserved: `yes`+- Compatibility class: records shipped behavior; the container emits only the+ canonical `nav-icon` target- Controlled/uncontrolled behavior: not applicable-- Migration decision: replace `navicon` theme keys and `.astryx-navicon` selectors- with `nav-icon` and `.astryx-nav-icon`, or run `astryx upgrade --from 0.6.3 --apply --path .`+- Migration decision: noneConsumer migration instructions belong in consumer docs and release notes.@@ -47,48 +66,54 @@ Consumer migration instructions belong in consumer docs and release notes.**Does not own / non-goals**-- The artwork or component supplied through `icon` — owned by the caller.+- The artwork or component supplied through `icon` — owned by the caller,+ including its accessible name or decorative status.- Interaction semantics — NavIcon remains a display-only container.+- Spacing the heading applies around a NavIcon — owned by+ `component:TopNavHeading` and `component:SideNavHeading`.## Public concepts-No new public concept is introduced. Consumer props and usage remain documented-in `NavIcon.doc.mjs`.+No component-local concept beyond the consumer props.## Behavioral and layout contract-| ID | Candidate invariant | Basis | Draft review state |-| --- | -------------------------------------------------------------------------------------- | ------------------------------- | -------------------------------------------------- |-| FR1 | The current render contains a circular container and the caller-supplied icon content. | Current source, docs, and tests | Verified current behavior; no new behavior decided |-| FR2 | The container carries the canonical `nav-icon` target. | Current source, docs, and tests | Verified canonical behavior; 0.7 alias removed |+| ID | Invariant | Basis |+| --- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- |+| FR1 | NavIcon renders one `<span>` circular container, centered, sized to `--size-element-md` on both axes, painted with the accent color and on-accent foreground, that contains `icon`. | Current source, docs, and tests |+| FR2 | The container carries only the canonical `nav-icon` target. | Current source, docs, and tests |+| FR3 | The container forwards its `ref`, `data-testid`, and other DOM props, and merges `className`, `style`, and `xstyle` after component styles. It adds no role, name, or focus stop. | Current source and tests |### Allowed variation-- Caller-supplied icon artwork and implementation may vary without becoming- NavIcon-owned anatomy.+- **AV1 — Artwork.** Caller-supplied icon artwork and implementation may vary+ without becoming NavIcon-owned anatomy.### Representative states-- The documented anatomy is the same for every caller-supplied icon.+| State | Required invariant | Allowed variation |+| -------- | ----------------------------------- | ----------------- |+| Any icon | Same circular container and target. | Artwork. |### Transformation and precedence order-- No new ordering rule is introduced.+- No precedence rule.### Performance and resources-- No new performance or resource rule is introduced.+- No resource rule.## Accessibility contract-This draft does not change or extend NavIcon's existing accessibility behavior.+- **AR1 — Transparent container.** NavIcon contributes no semantics; the+ caller's icon decides what assistive technology perceives (FR3).## Design relationships-| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |-| ---------------- | ---------------------------------------------- | ------------------------------ | ----------------- | ------------------ |-| Container | Presents the current circular painted surface. | Current source and public docs | Supporting | FR1, FR2 |-| Icon | Presents caller-supplied visual content. | Caller-supplied content | Context-dependent | FR1 |+| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |+| ---------------- | --------------------------------------------- | ------------------------------ | ----------------- | ------------------ |+| Container | Presents the circular accent painted surface. | Current source and public docs | Supporting | FR1, FR2 |+| Icon | Presents caller-supplied visual content. | Caller-supplied content | Context-dependent | FR1 |### Theming anatomy@@ -103,22 +128,25 @@ This draft does not change or extend NavIcon's existing accessibility behavior.## Family and system relationships-This draft references the current shared owners without restating their rules:-`architecture:component-theming-surface` and-`architecture:public-component-api`.+- `architecture:component-theming-surface` owns the target and its+ qualification.+- `architecture:public-component-api` owns how the forwarded inputs compose.## Verification map-| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |-| ------------------- | ------------------------------------ | ------------------------------------ | ------------------------------------------------------------------------------------- | ----------------------- |-| FR1 | `NavIcon.test.tsx` content suite | Caller-supplied icon | Removing the container or supplied content fails existing render and ref assertions. | `audit:NavIcon/anatomy` |-| FR2 | `NavIcon.test.tsx` target-name suite | Canonical target class | Missing or renamed canonical target fails the target assertion. | `audit:NavIcon/theming` |-| Theming anatomy map | `scripts/check-knowledge.mjs` | Canonical anatomy and current target | Missing, extra, prefixed, stale, or alias-backed mappings fail repository validation. | `audit:NavIcon/theming` |+| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |+| ------------------- | -------------------------------------------------------------- | ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- |+| FR1, FR3 | `NavIcon.test.tsx` content, ref, and test-id suites | Caller-supplied icon | Removing the container, content, ref, or test id fails. | `audit:NavIcon/anatomy` |+| FR2 | `NavIcon.test.tsx` target-name suite; `themingTargets.test.ts` | Canonical target class | A missing or renamed canonical target, or the removed `navicon` alias, fails the target assertion; an extra target fails `themingTargets.test.ts`. | `audit:NavIcon/theming` |+| Theming anatomy map | `scripts/check-knowledge.mjs` | Canonical anatomy and current target | Missing, extra, prefixed, stale, or alias-backed mappings fail repository validation. | `audit:NavIcon/theming` |++Read from source, with no focused test yet: the container's circular shape, size, and accent colors (FR1); and other DOM props, the `className`,+`style`, and `xstyle` merge, and the absence of a role, name, or focus stop+(FR3).## Decision log-None. This draft records current facts and introduces no component-local design-decision.+No component-local decision is recorded.## Open questions