@oneli8/react 1.0.0-beta.10

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@oneli8/react",
+  "version": "1.0.0-beta.10",
+  "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.css",
+    "ai-context.json",
+    "skills",
+    "PRINCIPLES.md",
+    "AGENTS.md",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "dependencies": {
+    "@oneli8/tokens": "1.0.0-beta.10"
+  },
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "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.js

@@ -0,0 +1,34 @@
+import { createElement } from 'react';
+import { OL8_ICONS, OL8_ICON_VIEWBOX } from '../foundations/icons.generated.js';
+import { isOl8IconName } from '../foundations/geometry.js';
+
+/**
+ * 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, 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/NavigationBadge.js

@@ -0,0 +1,19 @@
+import { createElement, forwardRef } from 'react';
+
+/**
+ * ATOM. Figma 989:484: "Content comes from item.badge; geometry and colors are
+ * semantic token controlled." One atom serves all three navigation organisms.
+ *
+ * The count sits beside a label that already names the destination, so it is
+ * not announced twice. A product that needs it announced spells it into the
+ * item's own accessible name.
+ */
+export const NavigationBadge = forwardRef(function NavigationBadge({ children, className = '', ...rest }, ref) {
+  if (children === undefined || children === null || children === '') {
+    throw new Error('[ol8] a navigation badge with nothing to say should not be rendered at all.');
+  }
+  return createElement('span', {
+    ...rest, ref, 'aria-hidden': 'true',
+    className: `ol8-nav-badge${className ? ` ${className}` : ''}`,
+  }, children);
+});

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 })
+  );
+}

package/src/foundations/geometry.js

@@ -0,0 +1,143 @@
+/**
+ * Framework free rules shared by every component. These are the parts of the
+ * system that are decisions rather than markup: which sizes exist, which
+ * combinations Figma approves, and which icon size a control carries.
+ */
+import { OL8_ICONS } from './icons.generated.js';
+
+/** Guard against an invented glyph name reaching a component. */
+export const isOl8IconName = (name) => Object.hasOwn(OL8_ICONS, name);
+
+export const OL8_BUTTON_VARIANTS = ['primary', 'secondary', 'quiet', 'destructive'];
+export const OL8_BUTTON_SIZES = ['compact', 'standard', 'comfortable', 'large'];
+export const OL8_MATERIALS = ['regular', 'gem'];
+/** Gem is approved for Primary and Secondary only (Figma 100:3). */
+export const GEM_VARIANTS = ['primary', 'secondary'];
+
+export const OL8_ICON_BUTTON_VARIANTS = OL8_BUTTON_VARIANTS;
+export const OL8_ICON_BUTTON_SIZES = OL8_BUTTON_SIZES;
+export const OL8_ICON_BUTTON_SHAPES = ['rounded', 'circle'];
+
+export const OL8_SELECTION_KINDS = ['checkbox', 'radio', 'switch'];
+export const OL8_SELECTION_SIZES = ['compact', 'comfortable'];
+export const OL8_SELECTION_STATES = {
+  checkbox: ['unchecked', 'checked', 'mixed'],
+  radio: ['unselected', 'selected'],
+  switch: ['off', 'on'],
+};
+
+export const OL8_CHOICE_KINDS = OL8_SELECTION_KINDS;
+export const OL8_CHOICE_SIZES = OL8_BUTTON_SIZES;
+export const OL8_LINK_FORMS = ['inline', 'standalone', 'navigation'];
+export const OL8_LINK_SIZES = ['small', 'standard', 'large'];
+export const OL8_LINK_MOTIONS = ['system', 'none'];
+
+export const OL8_TEXT_FIELD_SIZES = OL8_BUTTON_SIZES;
+export const OL8_TEXT_FIELD_APPEARANCES = ['outline', 'filled'];
+export const OL8_TEXT_FIELD_MATERIALS = OL8_MATERIALS;
+/** The four tones a message can carry. Pending is not one of them. */
+export const OL8_MESSAGE_TONES = ['critical', 'caution', 'positive', 'informative'];
+/** "Pending is a validation process status, not a fifth message tone." */
+export const OL8_VALIDATION_STATUSES = ['idle', 'pending', 'resolved'];
+/** Soft lets a person overshoot and then correct. Hard is for real technical limits. */
+export const OL8_CHARACTER_LIMIT_BEHAVIORS = ['soft', 'hard'];
+
+/** Form Message itself draws all five, because Figma 177:13 enumerates five. */
+export const OL8_FORM_MESSAGE_TONES = [...OL8_MESSAGE_TONES, 'pending'];
+/** Figma pairs one status icon with each tone (Form Message 177:13). */
+export const OL8_FORM_MESSAGE_ICONS = {
+  critical: 'critical',
+  caution: 'caution',
+  positive: 'positive',
+  informative: 'informative',
+  pending: 'loading',
+};
+
+export const OL8_NAVIGATION_SIZES = OL8_BUTTON_SIZES;
+export const OL8_TABS_HIERARCHIES = ['primary', 'secondary', 'tertiary'];
+export const OL8_TABS_ORIENTATIONS = ['horizontal', 'vertical'];
+export const OL8_TABS_ACTIVATIONS = ['automatic', 'manual'];
+/** "Declare exactly one behavior." */
+export const OL8_SEGMENT_BEHAVIORS = ['single', 'multi', 'momentary'];
+/** "Presentation never changes behavior." */
+export const OL8_SEGMENT_PRESENTATIONS = [
+  'inset-fill', 'line-indicator', 'outlined-selection', 'soft-pill', 'icon-only', 'stacked-label',
+];
+export const OL8_TAB_BAR_PRESENTATIONS = ['bottom', 'inline', 'sidebar', 'spatial-rail'];
+
+export const OL8_CHIP_SIZES = OL8_BUTTON_SIZES;
+export const OL8_TOKEN_SIZES = OL8_CHIP_SIZES;
+/** Figma draws the last three; `auto` resolves to one of them in code. */
+export const OL8_TOKEN_MARKS = ['auto', 'none', 'check', 'remove'];
+
+/** The contract's resolution, stated once so both packages agree. */
+export function resolveTokenMark(mark, { removable = true, selected = false } = {}) {
+  if (mark !== 'auto') return mark;
+  if (removable) return 'remove';
+  return selected ? 'check' : 'none';
+}
+
+export const OL8_OPTION_SIZES = ['standard', 'large'];
+export const OL8_POPUP_WIDTHS = ['content', 'anchor', 'wide'];
+export const OL8_POPUP_SIZES = OL8_OPTION_SIZES;
+export const OL8_MULTI_SELECT_SIZES = OL8_BUTTON_SIZES;
+export const OL8_MULTI_SELECT_APPEARANCES = ['outline', 'filled'];
+export const OL8_MULTI_SELECT_MATERIALS = OL8_MATERIALS;
+/** Constrained resolves from a known set; suggestive may also author values. */
+export const OL8_VALUE_POLICIES = ['constrained', 'suggestive'];
+
+export const OL8_COMBOBOX_SIZES = OL8_BUTTON_SIZES;
+export const OL8_COMBOBOX_APPEARANCES = ['outline', 'filled'];
+export const OL8_COMBOBOX_MATERIALS = OL8_MATERIALS;
+export const OL8_AUTOCOMPLETE_MODES = ['none', 'list-manual', 'list-automatic'];
+export const OL8_FILTER_SOURCES = ['local', 'remote', 'external'];
+
+export const OL8_PICKER_SIZES = OL8_BUTTON_SIZES;
+export const OL8_PICKER_MATERIALS = OL8_MATERIALS;
+export const OL8_COMMIT_BEHAVIORS = ['immediate', 'apply'];
+export const OL8_PICKER_PRESENTATIONS = ['inline', 'popup'];
+/** One treatment across an instance; peers never mix Check and None. */
+export const OL8_PICKER_MARKS = ['check', 'none'];
+
+export const OL8_POPUP_STATUSES = ['none', 'loading', 'empty', 'error'];
+export const OL8_AGGREGATE = ['none', 'some', 'all'];
+
+/** Compact and Standard take the 18px icon; Comfortable and Large take 24px. */
+export const iconSizeForButton = (size) =>
+  size === 'comfortable' || size === 'large' ? 24 : 18;
+
+/** Artwork sizes as BUILT in Figma: 18 / 18 / 24 / 24. */
+export const artworkSizeForIconButton = iconSizeForButton;
+
+/** The molecule's four sizes map onto the atom's two. */
+export const indicatorSizeFor = (size) =>
+  size === 'comfortable' || size === 'large' ? 'comfortable' : 'compact';
+
+/** Figma's Selection axis, derived from native input state. */
+export function selectionStateFor(kind, { checked = false, mixed = false } = {}) {
+  if (kind === 'checkbox') return mixed ? 'mixed' : checked ? 'checked' : 'unchecked';
+  if (kind === 'radio') return checked ? 'selected' : 'unselected';
+  return checked ? 'on' : 'off';
+}
+
+/** Disabled children are excluded from the tally. */
+export function computeAggregate(children) {
+  const boxes = [...children].filter((c) => !c.disabled);
+  if (boxes.length === 0) return 'none';
+  const checked = boxes.filter((c) => c.checked).length;
+  if (checked === 0) return 'none';
+  return checked === boxes.length ? 'all' : 'some';
+}
+
+export function assertVariant(variant, size, material) {
+  if (!OL8_BUTTON_VARIANTS.includes(variant)) throw new Error(`[ol8] unknown button variant "${variant}"`);
+  if (!OL8_BUTTON_SIZES.includes(size)) throw new Error(`[ol8] unknown button size "${size}"`);
+  if (!OL8_MATERIALS.includes(material)) throw new Error(`[ol8] unknown material "${material}"`);
+  if (material === 'gem' && !GEM_VARIANTS.includes(variant)) {
+    throw new Error(`[ol8] Gem has no approved treatment for "${variant}" — Figma 100:3 says Quiet and Destructive use the regular material.`);
+  }
+}
+
+let seq = 0;
+/** Stable within a render pass; React 18+ callers should pass their own useId. */
+export const autoId = (prefix) => `${prefix}-${(seq++).toString(36)}${Math.random().toString(36).slice(2, 7)}`;

package/src/foundations/icons.generated.d.ts

@@ -0,0 +1,48 @@
+// GENERATED by packages/sync/src/build-icons.mjs — do not edit by hand.
+// Source: Figma "Oneli8 Design System — 1.0.0-beta.1", page Iconography,
+// frame "Icon Library / Masters" (426:55). Re-run `npm run sync:icons`.
+
+export interface Ol8IconEntry {
+  /** Figma category segment: "Icon / <Category> / <Name>". */
+  readonly category: 'action' | 'navigation' | 'status' | 'selection'
+    | 'transport' | 'vitals' | 'maneuver';
+  /** Node id of the 24px master in Figma, or null while it is a candidate. */
+  readonly figmaNode: string | null;
+  /** True until the master is approved and mapped to a Figma node. */
+  readonly candidate?: boolean;
+  /** Semantic registry controls RTL mirroring (per Iconography documentation). */
+  readonly mirrorInRTL: boolean;
+  /** The ink Figma baked into the master, discarded in favour of currentColor. */
+  readonly sourceInk: string | null;
+  /** Drawing instructions in the canonical 24-unit source space. */
+  readonly body: string;
+}
+
+export declare const OL8_ICON_VIEWBOX: '0 0 24 24';
+export declare const OL8_ICONS: {
+  readonly "add": Ol8IconEntry;
+  readonly "caution": Ol8IconEntry;
+  readonly "check": Ol8IconEntry;
+  readonly "chevron-down": Ol8IconEntry;
+  readonly "chevron-up": Ol8IconEntry;
+  readonly "clear": Ol8IconEntry;
+  readonly "close": Ol8IconEntry;
+  readonly "copy": Ol8IconEntry;
+  readonly "critical": Ol8IconEntry;
+  readonly "forward": Ol8IconEntry;
+  readonly "heart": Ol8IconEntry;
+  readonly "informative": Ol8IconEntry;
+  readonly "loading": Ol8IconEntry;
+  readonly "maneuver-right": Ol8IconEntry;
+  readonly "mixed": Ol8IconEntry;
+  readonly "pause": Ol8IconEntry;
+  readonly "play": Ol8IconEntry;
+  readonly "positive": Ol8IconEntry;
+  readonly "search": Ol8IconEntry;
+  readonly "selected-dot": Ol8IconEntry;
+  readonly "skip-back": Ol8IconEntry;
+  readonly "skip-forward": Ol8IconEntry;
+  readonly "visibility-closed": Ol8IconEntry;
+  readonly "visibility-open": Ol8IconEntry;
+};
+export type Ol8IconName = keyof typeof OL8_ICONS;