@oneli8/react 1.0.0-beta.2 → 1.0.0-beta.4

package/AGENTS.md

@@ -0,0 +1,12 @@
+# OneLi8 public beta usage
+
+Read README.md and PRINCIPLES.md first. Public React exports are limited to Icon,
+iconNames, Button, IconButton and Link. Do not treat unused token families as
+available components. Use skills/oneli8-ui/SKILL.md for composition,
+skills/oneli8-icons/SKILL.md for icon work, and
+skills/oneli8-figma-to-code/SKILL.md for mapping work.
+
+Reuse canonical code and semantic tokens. Do not create consumer-local copies
+of existing icons, component skins or state geometry. Ask the maintainer about
+missing design decisions. This public beta does not enforce arbitrary downstream
+code automatically and does not claim complete Figma parity.

package/PRINCIPLES.md

@@ -0,0 +1,48 @@
+# OneLi8 principles
+
+OneLi8 is intended for broad human benefit and conceived as service to Guruji
+Shrii Arnav. His teachings inspire the project; implementation specifications
+are OneLi8's own work. Service, clarity, harmony, proportion, restraint and
+evolution guide its decisions.
+
+## Three distinct operating laws
+
+1. Atomic Design governs composition: atoms → molecules → organisms → templates
+   → pages. Icon plus label is a molecule, not a new atom. Private vector pieces
+   and layout wrappers need not become public components.
+2. OneLi8 Modularity governs ownership, reuse, semantic token dependencies,
+   optional-slot collapse and independent updates. Reuse an existing owner,
+   extend its API, or compose it before inventing another owner.
+3. Numerical atomicity governs the 3px construction rhythm and approved optical
+   exceptions, including the shared 1.8 icon stroke. Do not invent per-size strokes.
+
+An optional sixth level, Spatial Experience, follows Page; it is not an extra
+layer inside a button. Spatial ambition does not imply physical-device validation.
+
+## Materials and color
+
+Gem Morphism is a transparent material skin, not a separate component anatomy.
+Its four guiding qualities are Cut (bezel/edge), Color (semantic tint), Clarity
+(legibility), and Carat/weight (appropriate visual presence). Facets are rare
+accents, not mandatory decoration. Preserve near-white Gem content and test
+contrast on the actual backdrop; do not promise automatic background sensing.
+
+Regular and Gem reuse structure, measurements and behavior. Theme and primary
+color are independent. Product colors consume semantic/component roles rather
+than copied palette values. Use approved inward focus treatment without clipping
+or changing a control's outer dimensions.
+
+## Structural space
+
+Declare Fill, Hug or governed Fixed sizing. State surfaces share their owner's
+boundary. Parent inset plus child inset is intentional, not accidental duplicated
+padding. Removing an optional icon removes its gap. Preserve canonical spacing,
+radius relationships, typography and icon pool rather than drawing lookalikes.
+
+## Evidence before claims
+
+For new patterns, inspect Mobbin examples and relevant official interaction
+guidance, then apply OneLi8's own identity. For repairs, approved decisions and
+canonical owners come first. Record property, structural/token, visual and
+runtime evidence separately. Changes require a Figma/code impact assessment;
+no access or missing mapping means an explicit gap, not assumed synchronization.

package/README.md

@@ -1,101 +1,87 @@
-# OneLi8 Design System
+# @oneli8/react
 
-September 9, 2026 · Apache-2.0 · `1.0.0-beta.2`
-
-OneLi8 means One Light: a modular design system created by Akshay Dhore,
-inspired by Guruji Shrii Arnav and the 9×12 Way. This is a deliberately small
-public beta, not a completed SaaS suite or a claim of full Figma/code certification.
-
-## Included
-
-- React `Icon`, `iconNames`, `Button`, `IconButton`, and `Link`.
-- Existing Regular and Gem button treatments, without redesigning their source.
-- Canonical editable tokens, CSS variables, JavaScript, and Tailwind adapters.
-- Three AI skills, design principles, and explicit Button/IconButton/Link property mappings.
-
-Other component families are not exported. The complete token vocabulary is
-retained so its reference graph stays intact; tokens for another family do not
-mean that family's component implementation is included. Internal shared helpers
-are implementation details, not additional public components.
-
-## Install into an existing React project
-
-Requires Node 20+ and React 18+. React 18.3.1 is the tested version.
-Unzip this bundle, then use the two local archives in `tarballs/`:
+OneLi8 Design System for React.
 
 ```sh
-npm install /absolute/path/to/tarballs/oneli8-tokens-1.0.0-beta.2.tgz /absolute/path/to/tarballs/oneli8-react-1.0.0-beta.2.tgz
+npm install @oneli8/react
 ```
 
-These are local packages, not a claim that this version is on npm.
-
 ```jsx
-import {Button, IconButton, Icon, Link} from '@oneli8/react';
+import { Button, Icon } from '@oneli8/react';
 import '@oneli8/react/styles.css';
 
 export function Actions() {
-  return <div data-ol8-color-scheme="light" data-ol8-primary="blue">
-    <Button leadingIcon={<Icon name="add" />}>Add item</Button>
-    <IconButton accessibleName="Search" icon={<Icon name="search" />} />
-    <Link href="/help">Help</Link>
-  </div>;
+  return <Button variant="primary" leadingIcon="add">Add item</Button>;
 }
 ```
 
-This is a usage snippet, not an approved composed page. Use existing component
-properties and tokens when arranging your product. `material="gem"` is available
-on Button and IconButton, not Link. Test Gem content against its actual backdrop;
-near-white content alone cannot guarantee readable contrast.
+## What is included
 
-## API and tokens
+| Tier | Components |
+|---|---|
+| Atom | `Icon`, `SelectionIndicator` |
+| Molecule | `Button`, `IconButton`, `ChoiceItem`, `SelectionOption` |
+| Organism | `RadioGroup`, `CheckboxGroup` |
+| Material | Gem, an attribute adapter rather than a tier |
 
-The declaration files in `packages/react/src/` describe the API. Button variants
-are primary/secondary/quiet/destructive; sizes are compact/standard/comfortable/large.
-IconButton supports rounded/circle and requires an accessible name. Icons are
-decorative; give meaning to their parent control. Do not pass an invented icon
-name: choose from `iconNames`. Buttons select their shared icon size internally.
+## The system travels with the package
 
-Read `packages/tokens/README.md` for theme attributes and Tailwind adapters.
-Change editable `packages/tokens/src/` values, then run:
+If you need a component OneLi8 does not ship, build it from these foundations
+rather than inventing a parallel system. Everything needed to do that is inside
+the install:
 
-```sh
-node packages/tokens/scripts/build.mjs --standalone
-node packages/tokens/scripts/test.mjs --standalone
+| File | What it carries |
+|---|---|
+| `PRINCIPLES.md` | the design language and the three operating laws |
+| `ai-context.json` | the atomic rules, the component inventory, and how to extend |
+| `skills/oneli8-icons` | drawing a new glyph on the shared 1.8 stroke |
+| `skills/oneli8-ui` | composing with existing owners |
+| `skills/oneli8-figma-to-code` | reading the Figma source |
+| `AGENTS.md` | where an agent should start |
+
+The inventory in `ai-context.json` is generated from the source tree, so it can
+never describe a component that is not there.
+
+Point your agent at them:
+
+```
+Read @oneli8/react/ai-context.json and PRINCIPLES.md before writing any OneLi8 UI.
 ```
 
-This regenerates token files, not Figma. Repack/reinstall the packages after edits.
-Token status records describe development maturity, not public beta certification.
+## Rules that matter most
+
+Reach for a **semantic** token, never a primitive and never a literal.
+`--ol8-color-actionprimary-default`, not `--ol8-color-blue-600` and not
+`#2c438b`. Primitives are hidden from the Figma pickers for the same reason.
+
+Every dimension sits on the **3px grid**. An exception needs an approval record.
 
-## AI use and free Figma mapping
+Icons come from the pool. `OL8_ICONS` is the whole set, an invented name throws.
+A new glyph is a 24px neutral source on the shared **1.8 stroke**, never a
+per-size stroke.
 
-Start with `AGENTS.md` and choose a task-specific skill in `skills/`. AI tools
-that do not discover skills can read those Markdown instructions explicitly.
-Skills guide agents; they do not force arbitrary AI tools to comply automatically.
+Margins belong to the parent, never to the component.
 
-`mappings/` contains offline translators and dated canonical property tables.
-They accept inspected observations and return a component plan or explicit gaps.
-No Code Connect subscription, credentials, or network access is required to run
-them. They do not extract Figma automatically or certify visual parity. Copied
-Figma libraries can have different IDs: inspect and update mappings, never guess.
+States are not classes. There is no `.ol8-btn--hover`; there is `:hover`,
+`:active`, `:focus-visible`, `[disabled]` and `[data-ol8-loading]`.
 
-## Validation and limits
+## Accessibility is enforced, not suggested
 
-See `BUILD-REPORT.json` and `SMOKE-REPORT.json` for this artifact's checks.
-`SOURCE-MANIFEST.json` records hashes of reused source files. The React source
-owners and CSS are copied unchanged; package entry points are scoped to this release.
+`IconButton` throws without an `accessibleName`. `Button` throws for
+`material="gem"` on Quiet or Destructive, because Figma approves Gem for Primary
+and Secondary only. Errors rather than review comments, by design.
+
+## Theming
+
+Two independent attributes, set on any ancestor:
+
+```html
+<html data-ol8-color-scheme="dark" data-ol8-primary="orange">
+```
 
-Passing packaging, import, rendering, or mapping tests does not certify every
-browser state, screen-reader interaction, visual match, background, or XR device.
-Full-system synchronization remains incomplete. Report gaps rather than silently
-recreating components. This bundle has no backend, analytics, or credentials.
+To change the brand colour beyond the three built families, or to swap the
+typefaces, see `@oneli8/tokens/overrides.example.css`.
 
-## Ownership and evolution
+## Licence
 
-Akshay Dhore is currently the sole creator and approver of canonical OneLi8
-components. Apache-2.0 permits reuse and forks; upstream design approval is separate.
-Feedback and proposals are welcome, but no contribution process or additional
-maintainer is implied. Future releases can add fixed families incrementally.
-See `PRINCIPLES.md`, `LICENSE` and `NOTICE`. Preserve applicable copyright and
-attribution notices when redistributing under Apache-2.0. This does not require
-a visible badge in your product or imply OneLi8 endorsement. Earlier MIT releases
-retain their original permissions. This license update changes no component designs.
+Apache 2.0. Created by Akshay Dhore. See `LICENSE` and `NOTICE`.

package/ai-context.json

@@ -0,0 +1,146 @@
+{
+  "$comment": "GENERATED by packages/sync/src/build-package-context.mjs — do not edit.",
+  "system": "OneLi8",
+  "version": "1.0.0-beta.4",
+  "meaning": "OneLi8 means One Light.",
+  "foundations": {
+    "package": "@oneli8/tokens",
+    "css": "@oneli8/tokens/css",
+    "tokenPrefix": "--ol8-",
+    "namingAuthority": "Figma. Every variable carries an explicit codeSyntax, recorded verbatim in packages/tokens/src/figma-code-syntax.txt. Names are never derived from a rule.",
+    "rules": [
+      "Components consume SEMANTIC roles only. Primitives (color-<family>-<step>) are hidden from pickers in Figma and must not appear in component code.",
+      "color-primary-* is an alias ramp onto color-blue-* — identical values, distinct names. Prefer the semantic role over either.",
+      "Dimension scale is 3px-atomic. Even multiples for structural layout; odd multiples are deliberate optical or micro-gap choices.",
+      "Elevation ink is cyan-840 rgb(22,63,75) — never default black.",
+      "Typography roles are composite. Use the .ol8-type-<role> class, not the individual font vars.",
+      "shape-radius-full (999px) is reserved for pills and circles. Soft hexagons are component-specific recipes, not a radius token."
+    ]
+  },
+  "readFirst": [
+    "PRINCIPLES.md",
+    "AGENTS.md",
+    "skills/"
+  ],
+  "model": "React components. Same DOM and same stylesheets as @oneli8/core, verified identical.",
+  "architecture": {
+    "convention": "Atomic Design for developers (benjaminwfox.com/blog/tech/atomic-design-for-developers)",
+    "rules": [
+      "ATOM: composes no other component — native elements only. May hold internal state; must not read application state.",
+      "MOLECULE: composed of one or more atoms. Reusable, more specialised.",
+      "ORGANISM: composed of atoms/molecules/organisms. May hold business logic and application state.",
+      "MATERIALS are not an atomic tier. They are cross-cutting surface adapters applied by attribute (data-ol8-material) to an existing component, and live outside the hierarchy.",
+      "Assign margins to a component via its parent, NEVER to the component itself. Enforced by packages/sync/src/check-structure.mjs, which runs in npm run build."
+    ]
+  },
+  "components": [
+    {
+      "tier": "atom",
+      "module": "atoms/Icon.js",
+      "exports": [
+        "Icon"
+      ],
+      "constraint": "Composes no other component. Native elements only."
+    },
+    {
+      "tier": "atom",
+      "module": "atoms/SelectionIndicator.js",
+      "exports": [
+        "SelectionIndicator"
+      ],
+      "constraint": "Composes no other component. Native elements only."
+    },
+    {
+      "tier": "molecule",
+      "module": "molecules/Button.js",
+      "exports": [
+        "Button"
+      ],
+      "constraint": "Composed of atoms. Reusable and more specialised."
+    },
+    {
+      "tier": "molecule",
+      "module": "molecules/ChoiceItem.js",
+      "exports": [
+        "ChoiceItem"
+      ],
+      "constraint": "Composed of atoms. Reusable and more specialised."
+    },
+    {
+      "tier": "molecule",
+      "module": "molecules/IconButton.js",
+      "exports": [
+        "IconButton"
+      ],
+      "constraint": "Composed of atoms. Reusable and more specialised."
+    },
+    {
+      "tier": "molecule",
+      "module": "molecules/SelectionOption.js",
+      "exports": [
+        "SelectionOption"
+      ],
+      "constraint": "Composed of atoms. Reusable and more specialised."
+    },
+    {
+      "tier": "organism",
+      "module": "organisms/ChoiceGroup.js",
+      "exports": [
+        "RadioGroup",
+        "CheckboxGroup"
+      ],
+      "constraint": "Composed of atoms, molecules or organisms. May hold application state."
+    }
+  ],
+  "buildingWhatIsNotHere": {
+    "principle": "A component OneLi8 does not ship is still a OneLi8 component. Compose it from these foundations rather than inventing a parallel system.",
+    "steps": [
+      "Check the inventory below first. Do not rebuild something that exists.",
+      "Pick the tier by what it composes, not by how complex it feels.",
+      "Reach for a SEMANTIC token, never a primitive and never a literal. color-actionprimary-default, not color-blue-600 and not #2c438b.",
+      "Every dimension sits on the 3px grid. An exception needs an approval record, not a rounded number.",
+      "Icons come from the pool. To draw a new one follow skills/oneli8-icons: a 24px neutral source on the shared 1.8 stroke.",
+      "Give margins to the parent, never to the component.",
+      "States are not classes. Use :hover, :active, :focus-visible, [disabled] and data attributes.",
+      "Colour is currentColor on icons; the parent supplies the semantic role."
+    ],
+    "forbidden": [
+      "A literal colour, size or font value anywhere in a component.",
+      "A primitive token in a component. Primitives are hidden from the Figma pickers for the same reason.",
+      "An invented icon name. Choose from OL8_ICONS.",
+      "A per-size icon stroke. The 1.8 stroke is shared, and the 18px master is an exact 0.75 scale of the 24px one.",
+      "Mixing a filled treatment with an outlined one across selection controls. Checkbox and Radio share one language."
+    ]
+  },
+  "materials": {
+    "gem": {
+      "strategy": "attribute",
+      "emitAs": {
+        "data-ol8-material": "gem"
+      },
+      "note": "Gem is an attribute on an existing button, never a new class or variant. renderButton/renderIconButton throw for quiet and destructive.",
+      "appliesTo": {
+        "ol8-btn": [
+          "primary",
+          "secondary"
+        ],
+        "ol8-icon-btn": [
+          "primary",
+          "secondary"
+        ]
+      }
+    }
+  },
+  "pending": {
+    "Select and Combobox": {
+      "page": "1034:12628",
+      "remaining": {
+        "02 Selection Popup (organism)": "574:534, 6 variants — Width Content|Anchor|Wide x Size Standard|Large",
+        "03 Select Trigger": "583:338, 24 variants — Size x Appearance Outline|Filled x Condition",
+        "04 Choice Chip Foundation": "612:657 — Soft Hexagon 636:847 and Neutral 983:6552",
+        "05 Mobbin-informed Compositions": "603:281 (documentation)",
+        "06 Canonical Public Owners": "875:1399 (documentation)"
+      }
+    }
+  }
+}

package/package.json

@@ -1,39 +1,45 @@
 {
   "name": "@oneli8/react",
-  "version": "1.0.0-beta.2",
-  "type": "module",
+  "version": "1.0.0-beta.4",
+  "description": "OneLi8 Design System for React. Components, design tokens, the Gem material, and the design language they follow.",
+  "keywords": ["react", "design-system", "components", "design-tokens", "accessibility", "atomic-design", "oneli8"],
+  "homepage": "https://github.com/Akshay007ad/OneLi8-Design-System#readme",
+  "bugs": { "url": "https://github.com/Akshay007ad/OneLi8-Design-System/issues" },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Akshay007ad/OneLi8-Design-System.git",
+    "directory": "packages/react"
+  },
   "license": "Apache-2.0",
+  "author": "Akshay Dhore",
+  "type": "module",
+  "exports": {
+    ".": { "types": "./src/index.d.ts", "import": "./src/index.js", "default": "./src/index.js" },
+    "./styles.css": "./styles.css",
+    "./styles/*.css": "./src/styles/*.css",
+    "./ai-context.json": "./ai-context.json",
+    "./skills/*": "./skills/*",
+    "./package.json": "./package.json"
+  },
+  "types": "./src/index.d.ts",
+  "sideEffects": ["./styles.css", "**/*.css"],
   "files": [
     "src",
-    "styles",
     "styles.css",
+    "ai-context.json",
+    "skills",
+    "PRINCIPLES.md",
+    "AGENTS.md",
     "README.md",
     "LICENSE",
     "NOTICE"
   ],
-  "sideEffects": [
-    "./styles.css",
-    "./styles/*.css"
-  ],
-  "exports": {
-    ".": {
-      "types": "./src/index.d.ts",
-      "import": "./src/index.js"
-    },
-    "./styles.css": "./styles.css",
-    "./styles/accessibility.css": "./styles/accessibility.css",
-    "./styles/icon-frame.css": "./styles/icon-frame.css",
-    "./styles/button.css": "./styles/button.css",
-    "./styles/icon-button.css": "./styles/icon-button.css",
-    "./styles/gem-control-focus.css": "./styles/gem-control-focus.css",
-    "./styles/link.css": "./styles/link.css"
+  "dependencies": {
+    "@oneli8/tokens": "1.0.0-beta.4"
   },
   "peerDependencies": {
     "react": ">=18"
   },
-  "dependencies": {
-    "@oneli8/tokens": "1.0.0-beta.2"
-  },
-  "publishConfig": {"access":"public","tag":"beta"},
-  "repository": {"type":"git","url":"git+https://github.com/Akshay007ad/OneLi8-Design-System.git","directory":"packages/react"}
+  "engines": { "node": ">=20" },
+  "publishConfig": { "access": "public" }
 }

package/skills/oneli8-figma-to-code/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: oneli8-figma-to-code
+description: Translate inspected OneLi8 Button, IconButton and Link properties into canonical code without paid Code Connect.
+---
+
+Locate the bundle; read README.md, PRINCIPLES.md and the matching JSON and module
+in mappings/. These are property translators, not a Figma exporter. They need no
+paid Code Connect service. They do not supply a consumer's Figma access.
+
+Use an authorized connector, user-run read-only plugin, or manually supplied
+observations to obtain owner identity, exact properties, nested icon identities
+and token bindings. Never require enterprise Variables REST access. Screenshots
+alone support provisional visual work, not structural certification.
+
+Call mapButton, mapIconButton or mapLink with the shipped mapping and explicit
+observations; use the function signature in its module. Block unknown properties
+and missing identities. Copied libraries may change IDs: inspect rather than
+silently guessing. Do not build replacement HTML from a screenshot when a public
+owner exists. No component outside the public beta is supported by these adapters.
+
+Preserve approved Figma and decisions. Code mapping does not authorize changing
+Figma. Map focus/hover to real browser interactions, not invented public props.
+Verify properties, structural/token ownership, matched visual states, and runtime
+behavior separately. Record remaining gaps and observation dates. A mapped plan
+or successful render is not full synchronization or accessibility certification.

package/skills/oneli8-icons/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: oneli8-icons
+description: Reuse or propose additions to the OneLi8 public beta neutral 24px icon pool with shared presentation and color.
+---
+
+Locate the public beta bundle. Read PRINCIPLES.md, packages/react/src/atoms/Icon.js,
+packages/react/src/atoms/IconFrame.js and packages/react/src/Icon.d.ts. These are
+the actual drawing and presentation owners, not templates to copy into controls.
+
+Search iconNames first. Existing meaning uses its existing identity. For a missing
+meaning, propose one neutral 24×24 source definition in the pool and update the
+IconName type; no size-, color-, Gem- or consumer-specific duplicate masters.
+Follow adjacent approved geometry and the shared semantic stroke token. The
+shipped outlined paths use non-scaling-stroke; filled dots have no outline.
+Do not substitute historic proportional stroke rules or invent per-size values.
+
+Color follows currentColor and the consumer's semantic state. Button and
+IconButton already own their IconFrame sizing. A new icon is a candidate until
+Akshay approves it; an AI-generated candidate is not automatically canonical.
+This skill is guidance, not an autonomous icon-generation program.
+
+Test multi-part paths, clipping and color at 9, 12, 24 and a large display size;
+test swaps in light/dark and Regular/Gem. Compare Figma geometry/instance behavior
+when authorized access exists. Record unavailable checks instead of claiming sync.

package/skills/oneli8-ui/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: oneli8-ui
+description: Compose UI using the OneLi8 public beta components and tokens without recreating canonical owners.
+---
+
+Locate the extracted public beta bundle and read its README.md, PRINCIPLES.md and
+packages/react/src/index.d.ts. If unavailable, obtain it rather than inventing
+APIs. Paths here are relative to the bundle root.
+
+Before composition, record the public component, icon identity, semantic color,
+material, size and layout responsibility. Import from @oneli8/react; use generated
+tokens rather than copied values. Reuse source atoms inside their existing
+molecules. A new wrapper does not become a new atom merely because it is small.
+
+Keep optional slots collapsible and parent/child insets intentional. Do not copy
+private implementations into a product. For unsupported families, explicitly
+separate consumer-owned work from canonical OneLi8; do not claim it is provided.
+New canonical patterns need Mobbin visual research, official interaction guidance
+and maintainer approval, not copied visual identity.
+
+Check light/dark, Regular/Gem, focus, loading/disabled, accessible names and long
+content where applicable. Do not claim screen-reader testing from HTML checks.
+Record changed owners and the Figma/code impact; unavailable evidence stays open.
+The public beta's smoke tests verify packaging, not downstream UI correctness.

package/src/atoms/Icon.js

@@ -1,32 +1,34 @@
-import {createElement} from "react";
+import { createElement } from 'react';
+import { OL8_ICONS, OL8_ICON_VIEWBOX } from '../foundations/icons.generated.js';
+import { isOl8IconName } from '../foundations/geometry.js';
 
-const definitions={
-  "add":[["path",{d:"M12 5V19M5 12H19"}]],
-  "forward":[["path",{d:"M3 12H21M15 18L21 12L15 6"}]],
-  "critical":[["circle",{cx:12,cy:12,r:9}],["path",{d:"M9 9L15 15M15 9L9 15"}]],
-  "visibility-open":[["path",{d:"M3 12C5.25 8.25 8.25 6.375 12 6.375C15.75 6.375 18.75 8.25 21 12C18.75 15.75 15.75 17.625 12 17.625C8.25 17.625 5.25 15.75 3 12Z"}],["circle",{cx:12,cy:12,r:2.625}]],
-  "loading":[["path",{d:"M12 3C14.082 2.998 16.101 3.718 17.712 5.038C19.322 6.358 20.426 8.195 20.834 10.237C21.241 12.279 20.929 14.399 19.949 16.236C18.968 18.074 17.382 19.514 15.458 20.312C13.535 21.111 11.395 21.217 9.402 20.614C7.409 20.011 5.686 18.736 4.528 17.005C3.37 15.275 2.848 13.196 3.051 11.124C3.253 9.051 4.169 7.113 5.64 5.64"}]],
-  "caution":[["circle",{cx:12,cy:12,r:9}],["path",{d:"M12 7V13"}],["circle",{cx:12,cy:16.6,r:1,fill:"currentColor",stroke:"none"}]],
-  "positive":[["circle",{cx:12,cy:12,r:9}],["path",{d:"M7.6 12.2L10.6 15.2L16.6 9.2"}]],
-  "informative":[["circle",{cx:12,cy:12,r:9}],["path",{d:"M12 11V16"}],["circle",{cx:12,cy:7.6,r:1,fill:"currentColor",stroke:"none"}]],
-  "visibility-closed":[["path",{d:"M4.5 10.5C6.75 13.5 9.25 15 12 15C14.75 15 17.25 13.5 19.5 10.5M6.75 13.05L5.4 15M9.75 14.55L9.3 16.8M14.25 14.55L14.7 16.8M17.25 13.05L18.6 15"}]],
-  "chevron-down":[["path",{d:"M5 8.5L12 15.5L19 8.5"}]],
-  "chevron-up":[["path",{d:"M5 15.5L12 8.5L19 15.5"}]],
-  "search":[["path",{d:"M15 15L20 20M10 3C6.134 3 3 6.134 3 10C3 13.866 6.134 17 10 17C13.866 17 17 13.866 17 10C17 6.134 13.866 3 10 3Z"}]],
-  "clear":[["path",{d:"M5 5L19 19M19 5L5 19"}]],
-  "close":[["path",{d:"M6 6L18 18M18 6L6 18"}]],
-  "selection-check":[["path",{d:"M6.9 12.15L10.2 15.45L17.1 8.55"}]],
-  "selection-mixed":[["path",{d:"M7.5 12H16.5"}]],
-  "selection-dot":[["circle",{cx:12,cy:12,r:6,fill:"currentColor",stroke:"none"}]]
-};
-
-export const iconNames=Object.freeze(Object.keys(definitions));
+/**
+ * Icons are decorative by default. Meaning belongs to the parent control, so an
+ * unnamed icon is hidden from assistive technology rather than announced as an
+ * unlabelled graphic. Colour is never set here: every stroke and fill is
+ * currentColor and the consuming component supplies the semantic role.
+ */
+/** The bare <svg>, for slots that already carry the ol8-icon class. */
+export function IconGlyph({ name }) {
+  if (!isOl8IconName(name)) throw new Error(`[ol8] unknown icon "${name}".`);
+  return createElement('svg', { viewBox: OL8_ICON_VIEWBOX, fill: 'none', focusable: 'false' },
+    OL8_ICONS[name].elements.map((el, i) => createElement(el.tag, { key: i, ...el.attrs })));
+}
 
-export function Icon({name,className=""}){
-  const definition=definitions[name];
-  if(!definition)return null;
-  return createElement("svg",{className:["ol8-Icon",className].filter(Boolean).join(" "),viewBox:"0 0 24 24",fill:"none",
-    stroke:"currentColor",strokeWidth:"var(--ol8-component-icon-stroke)",strokeLinecap:"round",strokeLinejoin:"round",
-    "data-ol8-icon":name,"aria-hidden":"true",focusable:"false"},
-    ...definition.map(([element,props],index)=>createElement(element,{vectorEffect:props.stroke==="none"?undefined:"non-scaling-stroke",...props,key:index})));
+export function Icon({ name, size = 24, label, className = '', ...rest }) {
+  if (!isOl8IconName(name)) {
+    throw new Error(`[ol8] unknown icon "${name}". Choose from OL8_ICONS rather than inventing a name.`);
+  }
+  const semantic = typeof label === 'string' && label.length > 0;
+  return createElement(
+    'span',
+    {
+      ...rest,
+      className: `ol8-icon${className ? ` ${className}` : ''}`,
+      'data-ol8-icon': name,
+      'data-ol8-icon-size': size,
+      ...(semantic ? { role: 'img', 'aria-label': label } : { 'aria-hidden': 'true' }),
+    },
+    createElement(IconGlyph, { name })
+  );
 }

package/src/atoms/SelectionIndicator.js

@@ -0,0 +1,43 @@
+import { createElement } from 'react';
+import { IconGlyph } from './Icon.js';
+import { OL8_SELECTION_KINDS, OL8_SELECTION_STATES } from '../foundations/geometry.js';
+
+/**
+ * Only the checked checkbox carries artwork. Mixed and selected are drawn by
+ * CSS from the token geometry, and an unset control has no mark at all.
+ */
+function Mark({ kind, state, icon }) {
+  if (kind === 'checkbox') {
+    if (state === 'checked') return createElement('span', { className: 'ol8-selection__mark' }, createElement(IconGlyph, { name: 'check' }));
+    if (state === 'mixed') return createElement('span', { className: 'ol8-selection__mark' });
+    return null;
+  }
+  if (kind === 'radio') return state === 'selected' ? createElement('span', { className: 'ol8-selection__mark' }) : null;
+  return createElement('span', { className: 'ol8-selection__mark' },
+    icon ? createElement('span', { className: 'ol8-icon' }, createElement(IconGlyph, { name: icon })) : null);
+}
+
+/**
+ * ATOM. Purely presentational: it draws the mark a checkbox, radio or switch
+ * shows and owns no state, role or focus. The native input inside Choice Item
+ * owns all of that.
+ */
+export function SelectionIndicator({ kind, selection, size = 'compact', disabled = false, icon, className = '', ...rest }) {
+  if (!OL8_SELECTION_KINDS.includes(kind)) throw new Error(`[ol8] unknown selection kind "${kind}"`);
+  const states = OL8_SELECTION_STATES[kind];
+  const state = selection ?? states[0];
+  if (!states.includes(state)) throw new Error(`[ol8] "${state}" is not a ${kind} selection state`);
+  if (icon && kind !== 'switch') throw new Error('[ol8] only the switch thumb carries optional artwork');
+  return createElement(
+    'span',
+    {
+      ...rest,
+      className: `ol8-selection ol8-selection--${kind}${className ? ` ${className}` : ''}`,
+      'data-ol8-size': size,
+      'data-ol8-selection': state,
+      'data-ol8-availability': disabled ? 'disabled' : 'enabled',
+      'aria-hidden': 'true',
+    },
+    createElement(Mark, { kind, state, icon })
+  );
+}