@oneli8/core 1.0.0-beta.10

package/ai-context.json

@@ -0,0 +1,348 @@
+{
+  "$comment": "GENERATED by packages/sync/src/build-package-context.mjs — do not edit.",
+  "system": "OneLi8",
+  "version": "1.0.0-beta.10",
+  "meaning": "OneLi8 means One Light.",
+  "foundations": {
+    "package": "@oneli8/tokens",
+    "css": "@oneli8/tokens/css",
+    "tokenPrefix": "--ol8-",
+    "naming": {
+      "grammar": "Sanskrit grammar, not a CSS convention. Two rules follow from it and together they explain every name in the system. First, a compound that names ONE thing is written as one word: actionprimary is a single role rather than action plus primary, and cutedge is one feature of the Gem material, so action-primary would suggest two things where there is one. Second, a qualifier stays SEPARATE from what it qualifies: in --ol8-material-control-gem--primary-hover-start, hover is a state applied to start, two grammatical roles, so they stay apart. That is why disabledcontent is joined while hover-start is not. Hyphens separate levels of the hierarchy, never words inside a level. Words stay readable: no abbreviations, no truncation, no btn where button will do.",
+      "authority": "Figma is the authority on the result. Every variable there carries an explicit codeSyntax, copied verbatim into packages/tokens/src/figma-code-syntax.txt. Read a name from that record rather than re-deriving it from the grammar, because the file is not perfectly regular between siblings and guessing is how code and design drifted apart before. The grammar is the rule; the record is the spelling."
+    },
+    "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. Apply a whole role, all five of --ol8-typography-<role>-{font-family,font-size,font-weight,line-height,letter-spacing}, rather than picking loose font vars. This package ships custom properties and no class names.",
+      "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": "Framework agnostic. renderX() returns an HTML string; hydrateX() applies the runtime rules to markup that already exists.",
+  "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/icon.js",
+      "exports": [
+        "OL8_ICON_SIZES",
+        "isOl8IconName",
+        "renderIconSvg",
+        "renderIcon",
+        "hydrateIcons"
+      ],
+      "constraint": "Composes no other component. Native elements only."
+    },
+    {
+      "tier": "atom",
+      "module": "atoms/navigation-badge/navigation-badge.js",
+      "exports": [
+        "renderNavigationBadge"
+      ],
+      "constraint": "Composes no other component. Native elements only."
+    },
+    {
+      "tier": "atom",
+      "module": "atoms/selection-indicator/selection-indicator.js",
+      "exports": [
+        "OL8_SELECTION_KINDS",
+        "OL8_SELECTION_SIZES",
+        "OL8_SELECTION_STATES",
+        "renderSelectionIndicator"
+      ],
+      "constraint": "Composes no other component. Native elements only."
+    },
+    {
+      "tier": "molecule",
+      "module": "molecules/button/button.js",
+      "exports": [
+        "OL8_BUTTON_VARIANTS",
+        "OL8_BUTTON_SIZES",
+        "OL8_MATERIALS",
+        "GEM_VARIANTS",
+        "iconSizeForButton",
+        "renderButton",
+        "hydrateButtons",
+        "setButtonLoading"
+      ],
+      "constraint": "Composed of atoms. Reusable and more specialised."
+    },
+    {
+      "tier": "molecule",
+      "module": "molecules/choice-chip/choice-chip.js",
+      "exports": [
+        "OL8_CHIP_SIZES",
+        "renderChoiceChip",
+        "hydrateChoiceChips",
+        "syncChip"
+      ],
+      "constraint": "Composed of atoms. Reusable and more specialised."
+    },
+    {
+      "tier": "molecule",
+      "module": "molecules/choice-item/choice-item.js",
+      "exports": [
+        "OL8_CHOICE_KINDS",
+        "OL8_CHOICE_SIZES",
+        "indicatorSizeFor",
+        "selectionStateFor",
+        "renderChoiceItem",
+        "hydrateChoiceItems",
+        "syncIndicator",
+        "setChoiceMixed"
+      ],
+      "constraint": "Composed of atoms. Reusable and more specialised."
+    },
+    {
+      "tier": "molecule",
+      "module": "molecules/form-message/form-message.js",
+      "exports": [
+        "OL8_FORM_MESSAGE_TONES",
+        "OL8_FORM_MESSAGE_ICONS",
+        "renderFormMessage",
+        "hydrateFormMessages"
+      ],
+      "constraint": "Composed of atoms. Reusable and more specialised."
+    },
+    {
+      "tier": "molecule",
+      "module": "molecules/icon-button/icon-button.js",
+      "exports": [
+        "OL8_ICON_BUTTON_VARIANTS",
+        "OL8_ICON_BUTTON_SIZES",
+        "OL8_ICON_BUTTON_SHAPES",
+        "artworkSizeForIconButton",
+        "renderIconButton",
+        "hydrateIconButtons"
+      ],
+      "constraint": "Composed of atoms. Reusable and more specialised."
+    },
+    {
+      "tier": "molecule",
+      "module": "molecules/link/link.js",
+      "exports": [
+        "OL8_LINK_FORMS",
+        "OL8_LINK_SIZES",
+        "OL8_LINK_MOTIONS",
+        "renderLink",
+        "hydrateLinks"
+      ],
+      "constraint": "Composed of atoms. Reusable and more specialised."
+    },
+    {
+      "tier": "molecule",
+      "module": "molecules/select/select.js",
+      "exports": [
+        "OL8_SELECT_SIZES",
+        "OL8_SELECT_APPEARANCES",
+        "OL8_SELECT_MATERIALS",
+        "OL8_SELECT_NATIVE_POLICIES",
+        "renderSelect"
+      ],
+      "constraint": "Composed of atoms. Reusable and more specialised."
+    },
+    {
+      "tier": "molecule",
+      "module": "molecules/selection-option/selection-option.js",
+      "exports": [
+        "OL8_OPTION_SIZES",
+        "renderSelectionOption",
+        "setOptionSelected",
+        "setActiveOption"
+      ],
+      "constraint": "Composed of atoms. Reusable and more specialised."
+    },
+    {
+      "tier": "molecule",
+      "module": "molecules/text-field/text-field.js",
+      "exports": [
+        "OL8_TEXT_FIELD_SIZES",
+        "OL8_TEXT_FIELD_APPEARANCES",
+        "OL8_TEXT_FIELD_MATERIALS",
+        "OL8_MESSAGE_TONES",
+        "OL8_VALIDATION_STATUSES",
+        "OL8_CHARACTER_LIMIT_BEHAVIORS",
+        "renderTextField",
+        "hydrateTextFields",
+        "countGraphemes",
+        "clipToGraphemes"
+      ],
+      "constraint": "Composed of atoms. Reusable and more specialised."
+    },
+    {
+      "tier": "molecule",
+      "module": "molecules/token/token.js",
+      "exports": [
+        "OL8_TOKEN_SIZES",
+        "OL8_TOKEN_MARKS",
+        "resolveTokenMark",
+        "renderToken"
+      ],
+      "constraint": "Composed of atoms. Reusable and more specialised."
+    },
+    {
+      "tier": "organism",
+      "module": "organisms/choice-group/choice-group.js",
+      "exports": [
+        "OL8_AGGREGATE",
+        "computeAggregate",
+        "renderRadioGroup",
+        "renderCheckboxGroup",
+        "hydrateChoiceGroups"
+      ],
+      "constraint": "Composed of atoms, molecules or organisms. May hold application state."
+    },
+    {
+      "tier": "organism",
+      "module": "organisms/choice-picker/choice-picker.js",
+      "exports": [
+        "OL8_PICKER_SIZES",
+        "OL8_PICKER_MATERIALS",
+        "OL8_COMMIT_BEHAVIORS",
+        "OL8_PICKER_PRESENTATIONS",
+        "OL8_PICKER_MARKS",
+        "renderChoicePicker",
+        "hydrateChoicePickers"
+      ],
+      "constraint": "Composed of atoms, molecules or organisms. May hold application state."
+    },
+    {
+      "tier": "organism",
+      "module": "organisms/combobox/combobox.js",
+      "exports": [
+        "OL8_COMBOBOX_SIZES",
+        "OL8_COMBOBOX_APPEARANCES",
+        "OL8_COMBOBOX_MATERIALS",
+        "OL8_AUTOCOMPLETE_MODES",
+        "OL8_FILTER_SOURCES",
+        "renderCombobox",
+        "hydrateComboboxes"
+      ],
+      "constraint": "Composed of atoms, molecules or organisms. May hold application state."
+    },
+    {
+      "tier": "organism",
+      "module": "organisms/multi-select-field/multi-select-field.js",
+      "exports": [
+        "OL8_MULTI_SELECT_SIZES",
+        "OL8_MULTI_SELECT_APPEARANCES",
+        "OL8_MULTI_SELECT_MATERIALS",
+        "renderMultiSelectField",
+        "hydrateMultiSelectFields"
+      ],
+      "constraint": "Composed of atoms, molecules or organisms. May hold application state."
+    },
+    {
+      "tier": "organism",
+      "module": "organisms/segmented-control/segmented-control.js",
+      "exports": [
+        "OL8_SEGMENT_BEHAVIORS",
+        "OL8_SEGMENT_PRESENTATIONS",
+        "renderSegmentedControl",
+        "hydrateSegmentedControls"
+      ],
+      "constraint": "Composed of atoms, molecules or organisms. May hold application state."
+    },
+    {
+      "tier": "organism",
+      "module": "organisms/selection-popup/selection-popup.js",
+      "exports": [
+        "OL8_POPUP_WIDTHS",
+        "OL8_POPUP_SIZES",
+        "OL8_POPUP_STATUSES",
+        "renderSelectionPopup"
+      ],
+      "constraint": "Composed of atoms, molecules or organisms. May hold application state."
+    },
+    {
+      "tier": "organism",
+      "module": "organisms/tab-bar/tab-bar.js",
+      "exports": [
+        "OL8_TAB_BAR_PRESENTATIONS",
+        "renderTabBar",
+        "hydrateTabBars"
+      ],
+      "constraint": "Composed of atoms, molecules or organisms. May hold application state."
+    },
+    {
+      "tier": "organism",
+      "module": "organisms/tabs/tabs.js",
+      "exports": [
+        "OL8_TABS_HIERARCHIES",
+        "OL8_TABS_ORIENTATIONS",
+        "OL8_TABS_ACTIVATIONS",
+        "renderTabs",
+        "renderTabPanel",
+        "hydrateTabs"
+      ],
+      "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 an Icon Frame instance is an exact scale of the 24px master, so an 18px one carries a 1.35 stroke. The selection masters are the exception: Icon / Selection / Check keeps the same 10.2 x 6.9 artwork at 1.8 in both its 18 and 24 boxes, so it is not scaled.",
+      "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

@@ -0,0 +1,100 @@
+{
+  "name": "@oneli8/core",
+  "version": "1.0.0-beta.10",
+  "description": "OneLi8 Design System, framework agnostic. renderX returns an HTML string, hydrateX wires existing DOM. Ships the design language and the rules it follows.",
+  "keywords": [
+    "design-system",
+    "components",
+    "headless",
+    "framework-agnostic",
+    "design-tokens",
+    "accessibility",
+    "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/core"
+  },
+  "license": "Apache-2.0",
+  "author": "Akshay Dhore",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.js",
+      "default": "./src/index.js"
+    },
+    "./atoms": {
+      "types": "./src/atoms/index.d.ts",
+      "import": "./src/atoms/index.js",
+      "default": "./src/atoms/index.js"
+    },
+    "./molecules": {
+      "types": "./src/molecules/index.d.ts",
+      "import": "./src/molecules/index.js",
+      "default": "./src/molecules/index.js"
+    },
+    "./organisms": {
+      "types": "./src/organisms/index.d.ts",
+      "import": "./src/organisms/index.js",
+      "default": "./src/organisms/index.js"
+    },
+    "./styles.css": "./styles.css",
+    "./styles/icon.css": "./src/atoms/icon/icon.css",
+    "./styles/navigation-badge.css": "./src/atoms/navigation-badge/navigation-badge.css",
+    "./styles/selection-indicator.css": "./src/atoms/selection-indicator/selection-indicator.css",
+    "./styles/button.css": "./src/molecules/button/button.css",
+    "./styles/choice-chip.css": "./src/molecules/choice-chip/choice-chip.css",
+    "./styles/choice-item.css": "./src/molecules/choice-item/choice-item.css",
+    "./styles/form-message.css": "./src/molecules/form-message/form-message.css",
+    "./styles/icon-button.css": "./src/molecules/icon-button/icon-button.css",
+    "./styles/link.css": "./src/molecules/link/link.css",
+    "./styles/navigation-item.css": "./src/molecules/navigation-item/navigation-item.css",
+    "./styles/select.css": "./src/molecules/select/select.css",
+    "./styles/selection-option.css": "./src/molecules/selection-option/selection-option.css",
+    "./styles/text-field.css": "./src/molecules/text-field/text-field.css",
+    "./styles/token.css": "./src/molecules/token/token.css",
+    "./styles/choice-group.css": "./src/organisms/choice-group/choice-group.css",
+    "./styles/choice-picker.css": "./src/organisms/choice-picker/choice-picker.css",
+    "./styles/combobox.css": "./src/organisms/combobox/combobox.css",
+    "./styles/multi-select-field.css": "./src/organisms/multi-select-field/multi-select-field.css",
+    "./styles/segmented-control.css": "./src/organisms/segmented-control/segmented-control.css",
+    "./styles/selection-popup.css": "./src/organisms/selection-popup/selection-popup.css",
+    "./styles/tab-bar.css": "./src/organisms/tab-bar/tab-bar.css",
+    "./styles/tabs.css": "./src/organisms/tabs/tabs.css",
+    "./styles/gem.css": "./src/materials/gem/gem.css",
+    "./package.json": "./package.json",
+    "./ai-context.json": "./ai-context.json",
+    "./skills/*": "./skills/*"
+  },
+  "types": "./src/index.d.ts",
+  "sideEffects": [
+    "./styles.css",
+    "**/*.css"
+  ],
+  "files": [
+    "src",
+    "styles.css",
+    "ai-context.json",
+    "skills",
+    "PRINCIPLES.md",
+    "AGENTS.md",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "dependencies": {
+    "@oneli8/tokens": "1.0.0-beta.10"
+  },
+  "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,36 @@
+---
+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/foundations/icons.generated.js and packages/react/src/styles/icon.css.
+Icon owns drawing AND presentation: its `size` prop plus that stylesheet set the
+frame, so there is no separate IconFrame module and no Icon.d.ts — types live in
+index.d.ts and foundations/icons.generated.d.ts. These are the actual owners, not
+templates to copy into controls.
+
+Search OL8_ICONS first; isOl8IconName guards a name. 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. Icons
+scale GEOMETRICALLY from the 24px source, so the 1.8 stroke scales with the
+artwork: 1.35 at 18px, 1.8 at 24px, 3.6 at 48px. Verified against Figma — the
+Icon Frame Size=48 variant exports stroke-width 3.6 in a 48 viewBox (3.6/48 =
+1.8/24), and the Icon Frame's own description states that no per-size source or
+stroke tokens exist. The token set agrees: every stroke token is 1.8 and all 29
+stroked paths in the pool are 1.8; there is no 1.2/2.4 step scale.
+
+Do not put non-scaling-stroke on an icon. That belongs to Choice Chip
+terminals, which stretch unevenly under preserveAspectRatio="none" and need a
+constant edge; an icon scales uniformly and must not fight it. Filled marks
+have no outline. Do not invent per-size stroke 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,52 @@
+---
+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.
+
+Gem has two faces and they imply different content. Choosing the wrong pairing
+is the most common Gem error, in both directions: near-white ink on a stabilized
+face over a light page is invisible, and ordinary dark ink on an environmental
+face over daylight scenery is unreadable.
+
+material.gem.color.quiet.environmentalFace is a surface over imagery or the real
+world. Its content is material.gem.color.quiet.content, a stable near-white in
+BOTH appearances, and it carries the material.gem.color.quiet.contentGlow halo at
+material.gem.blur.contentGlow: four stacked shadows for text, three for control
+geometry, because 1.4.11 asks 3:1 of a graphical object where 1.4.3 asks 4.5:1 of
+text. That means every glyph AND the unselected control boundary and any icon, not
+the label alone. Disabled takes material.gem.color.quiet.contentDisabled, one
+whitish grey shared by text and control geometry, and no halo.
+
+material.gem.color.quiet.stabilizedFace is the local content plane on app chrome,
+including the filled Gem text field, Select and Combobox. Its content is ordinary
+color.text.* and takes no halo. Selected and mixed indicators are never restyled
+on either face; they fill with the primary action family and carry their own mark.
+
+material.gem.color.quiet.legibilityFace is the reduced-transparency mode. It is
+denser, never opaque, because Gem is worn and a solid surface would occlude the
+world for the person who needs help reading it. It uses the same content as the
+environmental face.
+
+Never thicken a face to win contrast, and never widen the halo: blur spreads a
+fixed alpha budget, so a wider halo is a weaker halo. docs/gem-material.md carries
+the measured values and the Figma node each was read from.
+
+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/icon.css

@@ -0,0 +1,54 @@
+/**
+ * Oneli8 · Icon atom
+ * Figma: page "Iconography" — masters "Icon Library / Masters" (426:55),
+ *        sizing from "Icon Frame" (418:51).
+ *
+ * Contract, straight from the Figma component descriptions:
+ *   - one canonical 24px source per glyph
+ *   - the Icon Frame *geometrically* scales the complete source instance, so
+ *     the 1.8-unit stroke scales with the artwork (48px icon => 3.6px stroke).
+ *     This is why the SVG keeps viewBox="0 0 24 24" and we size the box only —
+ *     never `vector-effect: non-scaling-stroke`.
+ *   - the source is neutral; the consumer supplies semantic color, which is
+ *     why every stroke/fill is `currentColor`.
+ */
+
+.ol8-icon {
+  /* The outer asset box. Defaults to the canonical 24px source size. */
+  --_ol8-icon-size: var(--ol8-size-icon-standard);
+
+  display: inline-flex;
+  flex: none;
+  align-items: center;
+  justify-content: center;
+  inline-size: var(--_ol8-icon-size);
+  block-size: var(--_ol8-icon-size);
+  /* Inherit ink from the consuming component (semantic color lives there). */
+  color: inherit;
+}
+
+/* The inner leaf. Both dimensions are explicit — never `auto`. */
+.ol8-icon > svg {
+  display: block;
+  inline-size: var(--_ol8-icon-size);
+  block-size: var(--_ol8-icon-size);
+  overflow: visible; /* matches the Figma export; round caps may kiss the edge */
+}
+
+/* ---- Icon Frame · universal sizes (Figma 418:51) ---------------------- */
+.ol8-icon[data-ol8-icon-size="9"]   { --_ol8-icon-size: var(--ol8-size-icon-micro); }
+.ol8-icon[data-ol8-icon-size="12"]  { --_ol8-icon-size: var(--ol8-size-icon-compact); }
+.ol8-icon[data-ol8-icon-size="18"]  { --_ol8-icon-size: var(--ol8-size-icon-small); }
+.ol8-icon[data-ol8-icon-size="24"]  { --_ol8-icon-size: var(--ol8-size-icon-standard); }
+.ol8-icon[data-ol8-icon-size="30"]  { --_ol8-icon-size: var(--ol8-size-icon-medium); }
+.ol8-icon[data-ol8-icon-size="36"]  { --_ol8-icon-size: var(--ol8-size-icon-large); }
+.ol8-icon[data-ol8-icon-size="48"]  { --_ol8-icon-size: var(--ol8-size-icon-xlarge); }
+.ol8-icon[data-ol8-icon-size="60"]  { --_ol8-icon-size: var(--ol8-size-icon-spacious); }
+.ol8-icon[data-ol8-icon-size="72"]  { --_ol8-icon-size: var(--ol8-size-icon-display); }
+.ol8-icon[data-ol8-icon-size="96"]  { --_ol8-icon-size: var(--ol8-size-icon-hero); }
+.ol8-icon[data-ol8-icon-size="108"] { --_ol8-icon-size: var(--ol8-size-icon-landmark); }
+
+/* ---- Direction ------------------------------------------------------- */
+/* "Direction: semantic registry controls RTL mirroring" (Iconography doc 84:13).
+   The registry sets data-ol8-icon-mirror; CSS only obeys it. */
+[dir="rtl"] .ol8-icon[data-ol8-icon-mirror="true"] > svg { transform: scaleX(-1); }

package/src/atoms/icon/icon.d.ts

@@ -0,0 +1,19 @@
+import type { Ol8IconName } from './icons.generated.js';
+
+export type Ol8IconSize = 9 | 12 | 18 | 24 | 30 | 36 | 48 | 60 | 72 | 96 | 108;
+export declare const OL8_ICON_SIZES: readonly Ol8IconSize[];
+
+export interface Ol8IconOptions {
+  /** One of the Icon Frame universal sizes. Defaults to the 24px source size. */
+  size?: Ol8IconSize;
+  /** Accessible name. Omit for decorative icons (the default). */
+  label?: string;
+  /** Extra classes on the outer box. */
+  className?: string;
+}
+
+export declare function isOl8IconName(name: string): name is Ol8IconName;
+export declare function renderIconSvg(name: Ol8IconName): string;
+export declare function renderIcon(name: Ol8IconName, options?: Ol8IconOptions): string;
+export declare function hydrateIcons(root?: ParentNode): void;
+export { OL8_ICONS, type Ol8IconName } from './icons.generated.js';