@astryxdesign/core 0.6.3-canary.f22695a → 0.6.3

package/src/Chat/ChatLayoutScrollButton.tsx

@@ -23,7 +23,6 @@ import {
   spacingVars,
   radiusVars,
   shadowVars,
-  sizeVars,
   durationVars,
   easeVars,
 } from '../theme/tokens.stylex';
@@ -68,14 +67,8 @@ const styles = stylex.create({
     borderRadius: radiusVars['--radius-full'],
     backgroundColor: colorVars['--color-background-popover'],
     boxShadow: shadowVars['--shadow-med'],
-    // The pill clips its own content, so it must track the height of the
-    // md Button it wraps. A literal would clip that Button under any theme
-    // that retunes the element scale.
-    height: sizeVars['--size-element-md'],
-    // `visibility` rides the same transition so the fade-out still plays:
-    // it flips to `visible` immediately on the way in and only at the end
-    // of the duration on the way out.
-    transitionProperty: 'opacity, transform, max-width, visibility',
+    height: '32px',
+    transitionProperty: 'opacity, transform, max-width',
     transitionTimingFunction: easeVars['--ease-standard'],
     transitionDuration: {
       default: durationVars['--duration-fast-max'],
@@ -85,19 +78,14 @@ const styles = stylex.create({
   hidden: {
     opacity: 0,
     pointerEvents: 'none',
-    // The hidden pill paints nothing, so focus landing on it would have no
-    // visible indicator (WCAG 2.2 SC 2.4.7). `opacity` and `pointer-events`
-    // leave the button in sequential focus navigation; `visibility` removes it.
-    visibility: 'hidden',
-    maxWidth: sizeVars['--size-element-md'],
+    maxWidth: '32px',
   },
   visible: {
     opacity: 1,
     pointerEvents: 'auto',
-    visibility: 'visible',
   },
   collapsed: {
-    maxWidth: sizeVars['--size-element-md'],
+    maxWidth: '32px',
   },
   expanded: {
     maxWidth: '200px',
@@ -139,25 +127,20 @@ export function ChatLayoutScrollButton({
 }: ChatLayoutScrollButtonProps) {
   const t = useTranslator();
   return (
-    // Two elements, two responsibilities. The outer one centres the pill and
-    // holds the gap above the composer — spacing outside the pill's border
-    // box, which the pill cannot own itself. The inner one is the pill: it is
-    // what a reader sees, so it carries the painted surface AND the public
-    // theming target. Keeping the target on the outer element would satisfy
-    // every automated check while leaving a theme styling an invisible
-    // full-width row (architecture:component-theming-surface INV4).
     <div
       ref={ref}
-      {...mergeProps(stylex.props(styles.wrapper, xstyle), className, style)}
+      {...mergeProps(
+        themeProps('chat-layout-scroll-button'),
+        stylex.props(styles.wrapper, xstyle),
+        className,
+        style,
+      )}
       {...rest}>
       <div
-        {...mergeProps(
-          themeProps('chat-layout-scroll-button'),
-          stylex.props(
-            styles.container,
-            isVisible ? styles.visible : styles.hidden,
-            label ? styles.expanded : styles.collapsed,
-          ),
+        {...stylex.props(
+          styles.container,
+          isVisible ? styles.visible : styles.hidden,
+          label ? styles.expanded : styles.collapsed,
         )}>
         <Button
           label={label ?? t('@astryx.chatLayoutScrollButton.scrollToBottom')}

package/src/Citation/Citation.doc.mjs

@@ -71,7 +71,7 @@ export const docs = {
       name: 'source',
       type: 'CitationSource',
       description:
-        'The citation source object containing title, url, an optional image src, and an optional icon node. The url follows the shared navigation rule described on the Link `href` prop; rejected destinations leave the citation visible without navigation. Image src uses separate resource handling.',
+        'The citation source object containing title, url, an optional image src, and an optional icon node.',
       required: true,
     },
     {
@@ -122,7 +122,7 @@ export const docsDense = {
   },
   propDescriptions: {
     source:
-      'citation source with title, url, optional image src, and optional icon. url follows the Link href navigation rule; rejected destinations stay visible without navigation. Image src handling is separate.',
+      'citation source object with title, url, optional image src, and optional icon node.',
     number: 'display index for this citation.',
     variant: 'display style: label chip with source title or compact numbered badge.',
   },

package/src/Citation/Citation.test.tsx

@@ -36,23 +36,6 @@ function atomicClasses(style: (typeof probe)[keyof typeof probe]): string[] {
 describe('Citation', () => {
   const source = {title: 'Example Source', url: 'https://example.com'};
 
-  it.each([
-    'javascript:alert(1)',
-    'vbscript:MsgBox(1)',
-    'data:text/html,<b>x</b>',
-    'java\nscript:alert(1)',
-  ])('renders rejected citation URL %s without navigation', url => {
-    const {container} = render(
-      <>
-        <Citation source={{title: 'Source', url}} number={1} />
-        <Citation source={{title: 'Source', url}} number={1} variant="number" />
-      </>,
-    );
-    expect(container.querySelector('a')).toBeNull();
-    expect(container.querySelector('[href]')).toBeNull();
-    expect(container.textContent).toBe('Source1');
-  });
-
   it('renders the source title as a link in the label variant', () => {
     render(<Citation source={source} number={1} data-testid="citation" />);
     const el = screen.getByTestId('citation');

package/src/Citation/Citation.tsx

@@ -4,7 +4,7 @@
 
 /**
  * @file Citation.tsx
- * @input Uses React, StyleX, theme tokens, and the shared navigation policy
+ * @input Uses React, StyleX, theme tokens
  * @output Exports Citation component for inline citation references
  * @position Core implementation; consumed by index.ts
  *
@@ -30,7 +30,6 @@ import {
   easeVars,
 } from '../theme/tokens.stylex';
 import {mergeProps} from '../utils';
-import {isSafeUrl} from '../utils/safeUrl';
 import type {BaseProps} from '../BaseProps';
 import {themeProps} from '../utils/themeProps';
 import {useTranslator} from '../i18n';
@@ -190,8 +189,7 @@ export function Citation({
 }: CitationProps): React.ReactElement {
   const t = useTranslator();
   const title = source.title ?? String(number);
-  const href =
-    source.url != null && isSafeUrl(source.url) ? source.url : undefined;
+  const href = source.url;
 
   // Resolve the source icon. A non-string `icon` node renders as-is (an Astryx
   // <Icon>, SVG, avatar, etc.). Otherwise fall back to an image URL: `src`, or

package/src/ClickableCard/ClickableCard.doc.mjs

@@ -22,7 +22,7 @@ export const docs = {
   props: [
     {name: 'label', type: 'string', description: 'Accessibility label.', required: true},
     {name: 'onClick', type: '(event: MouseEvent) => void', description: 'Click handler: fires on card surface only.'},
-    {name: 'href', type: 'string', description: 'Navigation URL. Plain, new-tab, Cmd/Ctrl-click, and middle-click activation all follow the shared navigation rule described on the Link `href` prop.'},
+    {name: 'href', type: 'string', description: 'Navigation URL.'},
     {name: 'target', type: 'string', description: 'Link target.', default: "'_self'"},
     {name: 'isDisabled', type: 'boolean', description: 'Disables the card.', default: 'false'},
     {name: 'children', type: 'ReactNode', description: 'Card content.'},
@@ -69,7 +69,7 @@ export const docsDense = {
   propDescriptions: {
     label: 'accessibility label',
     onClick: 'click handler: fires on card surface only',
-    href: 'navigation URL; every activation follows the shared navigation rule (see Link href)',
+    href: 'navigation URL',
     target: 'link target',
     isDisabled: 'disables card',
     padding: 'inner padding',

package/src/CodeBlock/highlightRanges.test.ts

@@ -4,18 +4,14 @@ import {describe, it, expect, vi, beforeEach, afterEach} from 'vitest';
 import {applyHighlightRangesChunked} from './highlightRanges';
 import type {TokenLine} from './tokenizer';
 
-// Mock CSS Highlight API. `escape` is real behavior, not a mock: the code
-// under test escapes generated names with it, so jsdom's implementation is
-// carried over when the CSS global is replaced.
+// Mock CSS Highlight API
 class MockHighlight extends Set<Range> {}
 const mockHighlightsMap = new Map<string, MockHighlight>();
-const realCssEscape = globalThis.CSS.escape;
 
 beforeEach(() => {
   mockHighlightsMap.clear();
 
   globalThis.CSS = {
-    escape: realCssEscape,
     highlights: {
       get: (name: string) => mockHighlightsMap.get(name),
       set: (name: string, h: MockHighlight) => mockHighlightsMap.set(name, h),
@@ -48,30 +44,6 @@ function createCodeElement(lines: string[]): HTMLElement {
   return code;
 }
 
-/**
- * The dynamic stylesheet is module-level state shared by every test in this
- * file, so each test drives unique token types and looks its rules up by the
- * escaped name rather than by position.
- */
-function dynamicRules(): CSSStyleRule[] {
-  const dynamicSheet = document.querySelector<HTMLStyleElement>(
-    'style[data-astryx-highlight-dynamic]',
-  );
-  return Array.from(dynamicSheet?.sheet?.cssRules ?? []) as CSSStyleRule[];
-}
-
-/**
- * Exactly the two highlight selectors and nothing else: an escaped ident may
- * contain any character, but only behind a backslash, so an unescaped `)`
- * that closed the function early (and the `, body` after it) cannot match.
- */
-const HIGHLIGHT_ONLY_SELECTOR =
-  /^\.astryx-code-block code::highlight\((?:[^()\\]|\\.)+\), \.astryx-codeeditor code::highlight\((?:[^()\\]|\\.)+\)$/;
-
-function highlightRule(name: string): string {
-  return `.astryx-code-block code::highlight(${name}), .astryx-codeeditor code::highlight(${name})`;
-}
-
 describe('applyHighlightRangesChunked', () => {
   it('creates ranges for tokens on each line', () => {
     const codeEl = createCodeElement(['const x = 1;', 'let y = 2;']);
@@ -95,120 +67,6 @@ describe('applyHighlightRangesChunked', () => {
     expect(kwHighlight!.size).toBe(0);
   });
 
-  it('keeps every parser-accepted tokenizer type coloured under its raw name', () => {
-    // The dotted type that crashed the block, plus names a narrow allowlist
-    // would wrongly reject even though the CSS parser accepts them all.
-    const types = ['keyword.control.sql', '_private', 'キーワード', '9start'];
-    const codeEl = createCodeElement(types.map(() => 'line'));
-    const tokenLines: TokenLine[] = types.map(type => [
-      {type, start: 0, end: 4},
-    ]);
-
-    const mockStyle = document.createElement('style');
-    mockStyle.setAttribute('data-astryx-highlight-styles', '');
-    document.head.appendChild(mockStyle);
-    const insertRule = vi.spyOn(CSSStyleSheet.prototype, 'insertRule');
-
-    const cleanup = applyHighlightRangesChunked(codeEl, tokenLines);
-
-    // Ranges register under the RAW names: a ::highlight() selector matches
-    // by ident value, so the escaped rule below still paints them.
-    for (const type of types) {
-      expect(mockHighlightsMap.get(`astryx-${type}`)?.size).toBe(1);
-    }
-
-    // One rule per type, with only the characters that need it escaped.
-    expect(insertRule.mock.calls.map(([rule]) => rule)).toEqual([
-      `${highlightRule('astryx-keyword\\.control\\.sql')} { color: var(--color-syntax-keyword\\.control\\.sql, currentColor); }`,
-      `${highlightRule('astryx-_private')} { color: var(--color-syntax-_private, currentColor); }`,
-      `${highlightRule('astryx-キーワード')} { color: var(--color-syntax-キーワード, currentColor); }`,
-      `${highlightRule('astryx-9start')} { color: var(--color-syntax-9start, currentColor); }`,
-    ]);
-
-    cleanup();
-  });
-
-  it('escapes the highlight name so a token type cannot leave its ::highlight() selector', () => {
-    // Unescaped, this type closes ::highlight() early and the CSS parser
-    // accepts what follows as a valid second selector plus a declaration
-    // block, with the trailing comment opener swallowing the rest of the
-    // generated rule text. The result is a rule that styles <body>.
-    const type = 'sel), body { background: red } /*';
-    const escapedName =
-      'astryx-sel\\)\\,\\ body\\ \\{\\ background\\:\\ red\\ \\}\\ \\/\\*';
-    const codeEl = createCodeElement(['line']);
-    const tokenLines: TokenLine[] = [[{type, start: 0, end: 4}]];
-
-    const mockStyle = document.createElement('style');
-    mockStyle.setAttribute('data-astryx-highlight-styles', '');
-    document.head.appendChild(mockStyle);
-    const insertRule = vi.spyOn(CSSStyleSheet.prototype, 'insertRule');
-
-    const cleanup = applyHighlightRangesChunked(codeEl, tokenLines);
-
-    expect(mockHighlightsMap.get(`astryx-${type}`)?.size).toBe(1);
-
-    // The exact rule text handed to the engine: both generated names fully
-    // escaped, one colour declaration, nothing of the payload's making.
-    expect(insertRule).toHaveBeenCalledTimes(1);
-    expect(insertRule).toHaveBeenCalledWith(
-      `${highlightRule(escapedName)} { color: var(--color-syntax-sel\\)\\,\\ body\\ \\{\\ background\\:\\ red\\ \\}\\ \\/\\*, currentColor); }`,
-    );
-
-    // And as parsed: the rule for this type keeps the payload inside the
-    // ident, and no rule in the sheet has any selector beyond the two
-    // highlight selectors.
-    const rules = dynamicRules();
-    const rule = rules.find(r => r.selectorText.includes('astryx-sel'));
-    expect(rule?.selectorText).toBe(highlightRule(escapedName));
-    for (const r of rules) {
-      expect(r.selectorText).toMatch(HIGHLIGHT_ONLY_SELECTOR);
-    }
-
-    cleanup();
-  });
-
-  it('escapes the custom property so a token type cannot add declarations', () => {
-    // Unescaped, this type closes var() early and the CSS parser accepts
-    // what follows as two more valid declarations.
-    const type = 'p); background: red; --x: var(--y';
-    const escapedName =
-      'astryx-p\\)\\;\\ background\\:\\ red\\;\\ --x\\:\\ var\\(--y';
-    const escapedColor =
-      'var(--color-syntax-p\\)\\;\\ background\\:\\ red\\;\\ --x\\:\\ var\\(--y, currentColor)';
-    const codeEl = createCodeElement(['line']);
-    const tokenLines: TokenLine[] = [[{type, start: 0, end: 4}]];
-
-    const mockStyle = document.createElement('style');
-    mockStyle.setAttribute('data-astryx-highlight-styles', '');
-    document.head.appendChild(mockStyle);
-    const insertRule = vi.spyOn(CSSStyleSheet.prototype, 'insertRule');
-
-    const cleanup = applyHighlightRangesChunked(codeEl, tokenLines);
-
-    expect(mockHighlightsMap.get(`astryx-${type}`)?.size).toBe(1);
-
-    expect(insertRule).toHaveBeenCalledTimes(1);
-    expect(insertRule).toHaveBeenCalledWith(
-      `${highlightRule(escapedName)} { color: ${escapedColor}; }`,
-    );
-
-    // As parsed: exactly one declaration, `color`, whose value is the
-    // escaped custom property with its fallback.
-    const rule = dynamicRules().find(r => r.selectorText.includes('astryx-p'));
-    expect(rule).toBeDefined();
-    expect(rule!.selectorText).toBe(highlightRule(escapedName));
-    const declared = Array.from({length: rule!.style.length}, (_, i) =>
-      rule!.style.item(i),
-    );
-    expect(declared).toEqual(['color']);
-    expect(rule!.style.getPropertyValue('color')).toBe(escapedColor);
-    expect(rule!.style.getPropertyValue('background')).toBe('');
-    expect(rule!.style.getPropertyValue('--x')).toBe('');
-
-    cleanup();
-  });
-
   it('handles empty token lines', () => {
     const codeEl = createCodeElement(['', 'const x = 1;']);
     const tokenLines: TokenLine[] = [[], [{type: 'keyword', start: 0, end: 5}]];

package/src/CodeBlock/highlightRanges.ts

@@ -64,21 +64,11 @@ function ensureDynamicHighlightType(tokenType: string): void {
     }
   }
 
-  // CSS.escape both generated names before they land in rule text: the
-  // registry key stays the raw string (a ::highlight() selector matches by
-  // ident VALUE, escapes and all), so dotted, non-ASCII, `_private`, and
-  // digit-led token types keep their colours — while nothing a token stream
-  // carries can step outside its ident and shape the rule.
-  const name = CSS.escape(`astryx-${tokenType}`);
-  const colorVar = `var(${CSS.escape(`--color-syntax-${tokenType}`)}, currentColor)`;
-  try {
-    dynamicStyleSheet.insertRule(
-      `.astryx-code-block code::highlight(${name}), .astryx-codeeditor code::highlight(${name}) { color: ${colorVar}; }`,
-    );
-  } catch {
-    // An engine that still refuses the rule costs that type its colour
-    // (ranges paint with currentColor) — never the whole code block.
-  }
+  const name = `astryx-${tokenType}`;
+  const colorVar = `var(--color-syntax-${tokenType}, currentColor)`;
+  dynamicStyleSheet.insertRule(
+    `.astryx-code-block code::highlight(${name}), .astryx-codeeditor code::highlight(${name}) { color: ${colorVar}; }`,
+  );
 }
 
 // ---------------------------------------------------------------------------

package/src/Icon/Icon.doc.mjs

@@ -49,9 +49,8 @@ export const docs = {
     {
       name: 'size',
       type: "'xsm' | 'sm' | 'md' | 'lg'",
-      description:
-        'Icon size. An explicit value wins. When omitted, Icon uses the nearest default supplied by an owning Astryx component for its icon slot, then falls back to md when no contextual default exists.',
-      default: "Contextual; otherwise 'md'",
+      description: 'Icon size.',
+      default: "'md'",
     },
     {
       name: 'label',
@@ -154,9 +153,8 @@ export const docsZh = {
     {
       name: 'size',
       type: "'xsm' | 'sm' | 'md' | 'lg'",
-      description:
-        '图标尺寸。显式值优先。省略时，Icon 使用最近的 Astryx 所属组件为其图标槽提供的默认尺寸；如果没有上下文默认值，则回退为 md。',
-      default: "上下文默认值；否则为 'md'",
+      description: '图标尺寸。',
+      default: "'md'",
     },
     {
       name: 'label',
@@ -296,7 +294,7 @@ export const docsDense = {
   propDescriptions: {
     icon: 'Semantic icon name or SVG component. Valid names: close, chevronDown, chevronLeft, chevronRight, chevronsLeft, chevronsRight, check, success, error, warning, info, calendar, clock, externalLink, menu, moreHorizontal, search, arrowUp, arrowDown, arrowsUpDown, funnel, eyeSlash, viewColumns, copy, checkDouble, wrench, stop, microphone. For others, pass an SVG component.',
     color: 'Color variant mapped to Astryx icon color tokens.',
-    size: "explicit Icon size; otherwise nearest owning-component default, then 'md' when no contextual default exists",
+    size: 'Icon size.',
     label:
       'Accessible name for a meaningful, standalone icon. Sets role="img" + aria-label and drops the default aria-hidden. Omit (default) for decorative icons (stays aria-hidden). Empty string = decorative. The accessible-name/alt-text prop for icons.',
     xstyle:

package/src/Icon/Icon.spec.md

@@ -10,18 +10,12 @@ approved_by: cixzhang
 approved_at: 2026-08-30
 owners: [cixzhang, imdreamrunner]
 review_triggers: [public-api, behavior, theming, accessibility]
-verified_by:
-  [
-    packages/core/src/Icon/Icon.test.tsx,
-    packages/core/src/IconButton/IconButton.test.tsx,
-    scripts/check-knowledge.mjs,
-  ]
+verified_by: [packages/core/src/Icon/Icon.test.tsx, scripts/check-knowledge.mjs]
 modules: []
 families: []
 design_specs: []
 architecture:
   [
-    architecture:component-size-cascade,
     architecture:component-theming-surface,
     architecture:icon-resolution-and-component-slots,
     architecture:public-component-api,
@@ -39,12 +33,11 @@ semantics. Consumer usage remains documented in `Icon.doc.mjs`.
 
 ## Compatibility and migration
 
-- Released default preserved: `yes` for explicit sizes and standalone Icons
-- Compatibility class: component-owned Icon slots may supply a contextual default;
-  explicit Icon sizes and the standalone `md` fallback remain unchanged
+- Released default preserved: `yes`
+- Compatibility class: additive documentation only; runtime, DOM, styling, and
+  public API remain unchanged
 - Controlled/uncontrolled behavior: not applicable
-- Migration decision: no consumer migration; omit `size` when the owning Astryx
-  component should select the contextual default
+- Migration decision: none; this record characterizes the released component
 
 Consumer migration instructions belong in consumer docs and release notes.
 
@@ -53,7 +46,6 @@ Consumer migration instructions belong in consumer docs and release notes.
 **Owns**
 
 - Accepting a semantic icon key or a supplied icon component as the glyph source.
-- Resolving explicit, component-owned contextual, and standalone size defaults.
 - Applying Icon's size, color, theming target, and accessibility semantics to
   the rendered glyph.
 
@@ -61,22 +53,19 @@ Consumer migration instructions belong in consumer docs and release notes.
 
 - The shared registry's key-resolution and fallback order — owned by the shared
   icon system.
-- Which contextual default an owning Astryx component selects for its icon slot —
-  owned by that component or family contract.
 - The meaning of a glyph in product context or whether nearby text makes it
   decorative — owned by the product callsite.
 - Interaction, focus, or control naming — owned by the interactive parent.
 - The artwork supplied by a consumer or registered through a theme.
-- A public Icon size-provider API; contextual transport is implementation detail.
 
 ## Public concepts
 
-| Concept       | Closed values or states                                   | Meaning                                                   | Availability by variant/orientation/state | Default                                         | Owner            | Stability | Invalid-value behavior                                 |
-| ------------- | --------------------------------------------------------- | --------------------------------------------------------- | ----------------------------------------- | ----------------------------------------------- | ---------------- | --------- | ------------------------------------------------------ |
-| Glyph source  | semantic key, namespaced extension key, or icon component | Selects the visual symbol.                                | Every render                              | Required                                        | `component:Icon` | Stable    | TypeScript rejects unsupported built-in string values. |
-| Size          | `xsm`, `sm`, `md`, `lg`                                   | Selects the icon box size.                                | Every rendered glyph                      | nearest component-owned default; otherwise `md` | `component:Icon` | Stable    | TypeScript rejects unsupported values.                 |
-| Color         | documented semantic and palette values                    | Selects the glyph color or inherits it from context.      | Every rendered glyph                      | `inherit`                                       | `component:Icon` | Stable    | TypeScript rejects unsupported values.                 |
-| Accessibility | decorative or meaningfully labelled                       | Controls whether assistive technology receives the glyph. | Every rendered glyph                      | Decorative                                      | `component:Icon` | Stable    | Empty labels use the decorative behavior.              |
+| Concept       | Closed values or states                                   | Meaning                                                   | Availability by variant/orientation/state | Default    | Owner            | Stability | Invalid-value behavior                                 |
+| ------------- | --------------------------------------------------------- | --------------------------------------------------------- | ----------------------------------------- | ---------- | ---------------- | --------- | ------------------------------------------------------ |
+| Glyph source  | semantic key, namespaced extension key, or icon component | Selects the visual symbol.                                | Every render                              | Required   | `component:Icon` | Stable    | TypeScript rejects unsupported built-in string values. |
+| Size          | `xsm`, `sm`, `md`, `lg`                                   | Selects the icon box size.                                | Every rendered glyph                      | `md`       | `component:Icon` | Stable    | TypeScript rejects unsupported values.                 |
+| Color         | documented semantic and palette values                    | Selects the glyph color or inherits it from context.      | Every rendered glyph                      | `inherit`  | `component:Icon` | Stable    | TypeScript rejects unsupported values.                 |
+| Accessibility | decorative or meaningfully labelled                       | Controls whether assistive technology receives the glyph. | Every rendered glyph                      | Decorative | `component:Icon` | Stable    | Empty labels use the decorative behavior.              |
 
 A namespaced key that does not resolve currently renders nothing. This is
 existing behavior, not an intentional fallback promise.
@@ -86,51 +75,42 @@ existing behavior, not an intentional fallback promise.
 Requirements identify their basis so observed code is not mistaken for an
 intentional decision.
 
-| ID  | Candidate invariant                                                                                                                                                                               | Basis                                                 | Draft review state                                      |
-| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- | ------------------------------------------------------- |
-| FR1 | Icon MUST present at most one glyph from the supplied semantic key, namespaced key, or icon component.                                                                                            | Documented promise and current tests.                 | Settled intent.                                         |
-| FR2 | Every rendered glyph MUST carry the `icon` theming target with its resolved size and selected color reflected as target data.                                                                     | Current source, docs, and theming tests.              | Settled intent.                                         |
-| FR3 | Icon MUST apply the resolved size as width and height for every glyph, plus font size where needed for 1em-based icon sources. This sizing contract MUST NOT promise an HTML or SVG element type. | Human decision, current source, and tests.            | Settled intent.                                         |
-| FR4 | Supported SVG and styling escape hatches MUST retain their established merge and override behavior.                                                                                               | Current source and regression tests.                  | Current compatibility behavior; verify before changing. |
-| FR5 | An explicit Icon `size` MUST win. Without one, Icon MUST use the nearest default supplied by an owning Astryx component for its documented icon slot; without such a default, Icon MUST use `md`. | Component-size precedence and Button sizing decision. | Settled intent.                                         |
+| ID  | Candidate invariant                                                                                                                                                                               | Basis                                      | Draft review state                                      |
+| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ | ------------------------------------------------------- |
+| FR1 | Icon MUST present at most one glyph from the supplied semantic key, namespaced key, or icon component.                                                                                            | Documented promise and current tests.      | Settled intent.                                         |
+| FR2 | Every rendered glyph MUST carry the `icon` theming target with its selected size and color reflected as target data.                                                                              | Current source, docs, and theming tests.   | Settled intent.                                         |
+| FR3 | Icon MUST apply the selected size as width and height for every glyph, plus font size where needed for 1em-based icon sources. This sizing contract MUST NOT promise an HTML or SVG element type. | Human decision, current source, and tests. | Settled intent.                                         |
+| FR4 | Supported SVG and styling escape hatches MUST retain their established merge and override behavior.                                                                                               | Current source and regression tests.       | Current compatibility behavior; verify before changing. |
 
 ### Allowed variation
 
 - **AV1 — Artwork.** The path, view box, and internal structure may vary by icon
   source or theme without changing Icon's one-part consumer anatomy.
-- **AV2 — Rendering strategy.** Icon may render a supplied icon component directly or
+- **AV2 — Rendering strategy.** Icon may render a supplied component directly or
   use an internal wrapper for a resolved key; neither element shape is public
   anatomy.
 - **AV3 — Theme and consumer styling.** Existing theme and styling escape hatches
   may change visual CSS properties without changing glyph ownership.
-- **AV4 — Contextual mapping.** An owning Astryx component may map its own public
-  size or variant to an Icon default. That mapping belongs to the owner and MUST
-  preserve explicit Icon sizes and the standalone fallback.
 
 ### Representative states
 
-| State                            | Required invariant                                       | Allowed variation                              |
-| -------------------------------- | -------------------------------------------------------- | ---------------------------------------------- |
-| Semantic key                     | One resolved glyph carries the `icon` target.            | Theme, registry, or built-in artwork.          |
-| Namespaced extension key         | A resolved extension glyph carries the `icon` target.    | Consumer- or library-owned artwork.            |
-| Supplied icon component          | The supplied glyph carries the `icon` target.            | Component implementation and SVG internals.    |
-| Standalone Icon without `size`   | The resolved size is `md`.                               | Glyph source and color.                        |
-| Owned icon slot without `size`   | The nearest documented component default is used.        | The owning component's declared size mapping.  |
-| Explicit Icon size in owned slot | The explicit Icon size wins over the contextual default. | Any supported Icon size.                       |
-| Unresolved namespaced key        | No glyph is currently rendered.                          | No fallback behavior is established by intent. |
+| State                     | Required invariant                                    | Allowed variation                              |
+| ------------------------- | ----------------------------------------------------- | ---------------------------------------------- |
+| Semantic key              | One resolved glyph carries the `icon` target.         | Theme, registry, or built-in artwork.          |
+| Namespaced extension key  | A resolved extension glyph carries the `icon` target. | Consumer- or library-owned artwork.            |
+| Supplied icon component   | The supplied glyph carries the `icon` target.         | Component implementation and SVG internals.    |
+| Unresolved namespaced key | No glyph is currently rendered.                       | No fallback behavior is established by intent. |
 
 ### Transformation and precedence order
 
-- **ORD1 — Size resolution.** Resolve explicit Icon `size` → nearest
-  component-owned contextual default → standalone `md` fallback.
-- **ORD2 — Presentation.** Apply the target, resolved size, and component color
-  styles, then merge consumer `xstyle`, `className`, inline `style`, and supported
+- **ORD1 — Presentation.** Apply the target, component size and color styles,
+  then merge consumer `xstyle`, `className`, inline `style`, and supported
   pass-through props in their established order.
 
 ### Performance and resources
 
 - **PR1 — Render work.** Icon owns no listeners, observers, or layout
-  measurement; semantic and size resolution are synchronous during render.
+  measurement; semantic resolution is synchronous during render.
 
 ## Accessibility contract
 
@@ -143,9 +123,9 @@ intentional decision.
 
 ## Design relationships
 
-| Anatomy or state | Design requirement                                                 | Representation authority                                      | Hierarchy role    | Component contract |
-| ---------------- | ------------------------------------------------------------------ | ------------------------------------------------------------- | ----------------- | ------------------ |
-| Glyph            | Carries the resolved visual symbol at the resolved size and color. | Consumer or registry selects artwork; Icon owns presentation. | Context-dependent | FR1, FR2, FR3, FR5 |
+| Anatomy or state | Design requirement                                                  | Representation authority                                      | Hierarchy role    | Component contract |
+| ---------------- | ------------------------------------------------------------------- | ------------------------------------------------------------- | ----------------- | ------------------ |
+| Glyph            | Carries the selected visual symbol at the requested size and color. | Consumer or registry selects artwork; Icon owns presentation. | Context-dependent | FR1, FR2, FR3      |
 
 `Glyph` is the single conceptual consumer part in both source modes. Current
 implementation may render a supplied icon component directly or place a
@@ -164,32 +144,26 @@ not promise a `span`, `svg`, or other element type.
 
 ## Family and system relationships
 
-- `architecture:component-size-cascade` owns the shared explicit → nearest
-  provider → component fallback pattern and requires provider ownership to be
-  declared. Icon retains its own `xsm | sm | md | lg` axis outside the standard
-  element-size cascade and adopts that precedence for component-owned defaults.
 - `architecture:component-theming-surface` owns the qualification and validation
   rules for the `icon` target.
 - `architecture:icon-resolution-and-component-slots` owns semantic-key and
   component-slot resolution before Icon renders the selected source.
 - `architecture:public-component-api` owns admission and compatibility rules for
-  Icon's public props and observable defaults.
-- The owning component or family specifies each contextual Icon-size mapping.
-  The Button family currently maps `sm` and `md` controls to `sm` Icons and `lg`
-  controls to `md` Icons.
+  Icon's public props.
 - Icon has no current family contract.
 
 ## Verification map
 
-| Contract            | Verification                                                                   | Representative states                                           | Mutation or failure expectation                                                                                                             | Audit section              |
-| ------------------- | ------------------------------------------------------------------------------ | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- |
-| FR1, FR3, FR5       | `Icon.test.tsx` sizing suites and `IconButton.test.tsx` contextual-size suites | standalone default; Button sizes; explicit override; both modes | Breaking source rendering, standalone fallback, contextual mapping, explicit precedence, or cross-mode sizing fails assertions.             | `audit:Icon/behavior`      |
-| FR2, FR4            | `Icon.test.tsx` target/styling suites plus source inspection                   | Both source modes; size and color variants                      | Removing the target or breaking override composition fails existing assertions; `data-color` reflection currently lacks focused assertions. | `audit:Icon/theming`       |
-| AR1, AR2, AR3       | `Icon.test.tsx` accessible-name suites                                         | Decorative, labelled, explicit ARIA override                    | Changing default or labelled semantics fails accessibility assertions.                                                                      | `audit:Icon/accessibility` |
-| Theming anatomy map | `scripts/check-knowledge.mjs`                                                  | Canonical consumer anatomy and current target                   | Missing, extra, prefixed, or stale mappings fail repository validation.                                                                     | `audit:Icon/theming`       |
+| Contract            | Verification                                                 | Representative states                         | Mutation or failure expectation                                                                                                                            | Audit section              |
+| ------------------- | ------------------------------------------------------------ | --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- |
+| FR1, FR3            | `Icon.test.tsx` source-mode and sizing suites                | Built-in, themed, namespaced, component       | Breaking source rendering or cross-mode sizing fails assertions.                                                                                           | `audit:Icon/behavior`      |
+| FR2, FR4            | `Icon.test.tsx` target/styling suites plus source inspection | Both source modes; size and color variants    | Removing the target or breaking override composition fails existing assertions; `data-size` and `data-color` reflection currently lack focused assertions. | `audit:Icon/theming`       |
+| AR1, AR2, AR3       | `Icon.test.tsx` accessible-name suites                       | Decorative, labelled, explicit ARIA override  | Changing default or labelled semantics fails accessibility assertions.                                                                                     | `audit:Icon/accessibility` |
+| Theming anatomy map | `scripts/check-knowledge.mjs`                                | Canonical consumer anatomy and current target | Missing, extra, prefixed, or stale mappings fail repository validation.                                                                                    | `audit:Icon/theming`       |
 
-Focused coverage for `data-color` on both glyph source modes is a checkable test
-gap; source inspection is the current evidence for that part of FR2.
+Focused coverage for `data-size` and `data-color` on both glyph source modes is
+a checkable test gap; source inspection is the current evidence for that part of
+FR2.
 
 ## Decision log
 
@@ -208,21 +182,6 @@ a `span`, `svg`, or other element.
 Rejected: separate wrapper and SVG anatomy entries, because those describe
 implementation strategies rather than stable consumer concepts.
 
-### DEC-2 — Owning components may provide contextual Icon defaults
-
-**Reference:** `component:Icon/DEC-2`
-**Decider:** cixzhang, 2026-09-23
-
-A person should see an icon that is proportionate to the Astryx component that
-owns its slot without every caller repeating a size. The owning component may
-therefore provide the default while an explicit Icon size remains authoritative
-and a standalone Icon remains `md`. Provider objects, hooks, and context shape
-remain private implementation details rather than public API.
-
-Rejected: an unconditional `md` default inside every composition, forcing every
-caller to repeat the owner-derived size, and exposing the provider mechanism as
-public API.
-
 ## Open questions
 
 None.