@ternent/core 0.0.1

package/packages/ui/src/design-system/base.css

@@ -0,0 +1,8 @@
+:root {
+  color-scheme: light dark;
+}
+
+:focus-visible {
+  outline: 2px solid var(--ui-ring);
+  outline-offset: 2px;
+}

package/packages/ui/src/design-system/docs/ACCESSIBILITY_RULES.md

@@ -0,0 +1,186 @@
+# ACCESSIBILITY_RULES
+
+## Goal
+
+Accessibility is a built-in requirement of the design system, not a later enhancement.
+AI must treat accessibility as part of the primitive contract.
+
+## Current repo baseline
+
+The accessibility contract is ahead of the current primitive implementation.
+
+- `Button` established the baseline for focus treatment in the current v2 primitive layer.
+- `Accordion` is the canonical disclosure primitive in `src/primitives`, and several Ark-backed accessibility patterns also exist in legacy `src/components/S*` files as behavior reference only.
+- Some existing primitives such as `SplitButton` predate the full contract in this document.
+- Primitive `*.spec.md` files now exist for the active v2 surface, so future interactive primitive work must update them rather than assume documentation can lag behind behavior.
+
+## Core principles
+
+1. keyboard access must work without mouse interaction
+2. focus visibility must be present and consistent
+3. semantics must match the component role
+4. ARIA must be correct, not decorative
+5. disabled and invalid states must remain understandable
+6. stateful behavior must be operable and perceivable
+
+## Focus treatment
+
+All interactive primitives must implement a consistent focus-visible style using system tokens.
+
+Preferred pattern based on current repo tokens:
+
+- `focus-visible:outline-none`
+- `focus-visible:ring-2`
+- `focus-visible:ring-[var(--ui-ring)]`
+
+The exact ring width may vary if the system later defines a dedicated token, but the treatment must remain consistent across primitives.
+
+## Native elements first
+
+Use native semantics whenever practical.
+
+Examples:
+
+- use `<button>` for clickable button behavior
+- use `<input>` for text entry
+- use `<textarea>` for multiline text
+- use `<label>` for labels
+
+Do not replace native semantics with generic elements unless the component model truly requires it.
+
+## Polymorphism caution
+
+If a primitive supports `as` or similar polymorphism:
+
+- ensure semantic responsibility stays correct
+- do not allow broken combinations silently
+- do not apply button-only attributes to links
+- document expectations in the spec
+
+## Disabled state
+
+Disabled controls must:
+
+- be visibly distinguishable
+- not appear interactive
+- not retain misleading hover behavior
+- not trap focus unexpectedly
+
+If a component uses a non-native disabled pattern, it must still communicate state through both semantics and styling.
+
+## Invalid state
+
+When a control supports invalid state:
+
+- expose the state clearly in styling
+- wire ARIA invalid semantics where appropriate
+- ensure associated messages can be referenced where relevant
+
+## Ark UI usage
+
+Ark UI should be the default foundation for primitives with meaningful a11y/state complexity.
+
+Use Ark UI for:
+
+- Checkbox
+- RadioGroup
+- Switch
+- Dialog
+- Tooltip
+- Popover
+- Menu
+- Tabs
+- Select
+- Combobox
+- Accordion
+
+When using Ark UI:
+
+1. rely on its semantics rather than reimplementing them poorly
+2. expose a clean system-level API on top
+3. keep styling token-driven
+4. document keyboard behavior in the spec
+5. use legacy Ark-backed `S*` components for behavior reference only, not as implementation dependencies
+
+## Keyboard expectations by primitive type
+
+### Button-like
+
+- Enter and Space should activate native buttons as expected
+- focus-visible must be present
+
+### Input-like
+
+- labels should be connectable
+- invalid and disabled state must remain clear
+- placeholder must not be the only form of instruction
+
+### Checkbox, RadioGroup, Switch
+
+- keyboard interaction must match expected native or ARIA behavior
+- labels must be clearly associated
+- state change must be perceivable
+
+### Dialog
+
+- focus should move into the dialog on open
+- focus should be constrained appropriately while open
+- Escape behavior should be documented if supported
+- returning focus on close should be handled correctly when possible
+
+### Menu and Popover
+
+- keyboard navigation must be coherent
+- open and close behavior must be predictable
+- menu items must have correct semantics
+
+### Tabs
+
+- tablist semantics must be correct
+- active tab state must be exposed properly
+- keyboard movement should follow expected conventions
+
+## Icon-only controls
+
+If a control is icon-only, it must have an accessible name.
+This may come from:
+
+- `aria-label`
+- visually hidden text
+- a clearly connected accessible label
+
+Do not ship icon-only controls with no accessible name.
+
+## Content and contrast
+
+The design system should prefer token combinations that maintain sufficient contrast.
+AI should avoid creating states that sacrifice readability for stylistic subtlety.
+
+## Motion
+
+Motion should support clarity and state change, not create confusion.
+Avoid flashy or unnecessary animation in primitives.
+
+## Spec requirement
+
+Each interactive primitive spec should document:
+
+- semantics used
+- keyboard behavior
+- focus behavior
+- disabled behavior
+- invalid behavior where relevant
+- Ark UI dependency if present
+
+Current repo note: interactive primitive changes should update the relevant spec file as part of the implementation work.
+
+## Review checklist
+
+Before merging an interactive primitive, confirm:
+
+- can it be used by keyboard?
+- does it have visible focus?
+- are semantics correct?
+- is ARIA meaningful rather than decorative?
+- does disabled state behave correctly?
+- is the behavior documented?

package/packages/ui/src/design-system/docs/AI_SYSTEM.md

@@ -0,0 +1,281 @@
+# AI_SYSTEM
+
+## Mission
+
+Build `ternent-ui` into a coherent, token-driven, multi-theme Vue design system that can be safely extended by AI without architectural or visual drift.
+
+The system must allow Sam to operate primarily as reviewer, orchestrator, and approver rather than hands-on implementer.
+
+## Repo model
+
+Treat the codebase as three layers.
+
+### 1. Legacy layer
+
+`src/components/S*`
+
+This is the old UI kit.
+It may be used as behavior reference and migration reference only.
+No new reusable UI should be added here.
+Do not use legacy components as dependencies for new primitives.
+Do not copy legacy APIs blindly.
+
+### 2. Design-system core
+
+`src/primitives/*`
+
+This is the future-facing reusable UI surface.
+All new reusable components must be built here.
+This is the only layer that should be exported as the stable primitive API.
+
+### 3. Composed patterns
+
+`src/patterns/*`
+
+This layer is for higher-level reusable compositions built from primitives.
+It now exists in the repo and should be used deliberately for product-agnostic compositions.
+Patterns are not low-level primitives.
+Patterns may be opinionated but must remain product-agnostic.
+
+## Current repo state
+
+The v2 layer is not a clean slate yet.
+
+- `src/primitives/Button/*` established the first canonical template and remains the baseline for future primitive structure.
+- `src/primitives/Accordion/*` is the canonical disclosure primitive, while `Accordian/*` remains as compatibility debt during migration.
+- `src/primitives/SplitButton/*` is exported today, but it is not yet documented by the current primitive contract.
+- Primitive `*.spec.md` files now exist for the current v2 surface and should be updated alongside implementation changes.
+- `src/primitives/index.ts` is the current public primitive export surface.
+
+## Taxonomy
+
+### Primitive
+
+A primitive is:
+
+- reusable across products
+- token-driven
+- not business-specific
+- usually small or medium in scope
+- safe for broad public export
+- visually and behaviorally consistent with the system
+
+Examples:
+
+- Button
+- Input
+- Textarea
+- Checkbox
+- RadioGroup
+- Switch
+- Dialog
+- Tooltip
+- Popover
+- Tabs
+- Badge
+- Card
+- Spinner
+- Skeleton
+- Separator
+
+### Pattern
+
+A pattern is:
+
+- composed from primitives
+- opinionated in layout or grouping
+- still product-agnostic
+- not the lowest-level building block
+
+Examples:
+
+- FormField
+- SearchField
+- EmptyState
+- FilterBar
+- PageHeader
+- SidebarNav
+- AppShell
+- CommandMenu
+
+### App component
+
+An app component is:
+
+- business-specific
+- domain-specific
+- not part of the shared design-system core
+
+Examples:
+
+- PackRevealPanel
+- LedgerAuditHeader
+- ProjectStatusCard
+
+App components must not be added to the design system package unless there is a clear shared-system reason.
+
+## Non-negotiable rules
+
+1. `src/primitives` is the only source for new reusable UI.
+2. `src/components/S*` is legacy and must not be extended with new work.
+3. New primitives must not depend on legacy `S*` components.
+4. Product-specific logic must not enter `src/primitives`.
+5. All reusable public exports must come from `src/primitives/index.ts` or `src/patterns/index.ts`.
+6. All primitives must consume semantic design tokens only.
+7. No raw Tailwind color utilities in primitives.
+8. No arbitrary spacing, radius, or motion values unless first added to the system contract.
+9. Theme support must come from token mapping, not per-component theme branching.
+10. AI must favor consistency and composability over cleverness.
+
+## Existing token reality
+
+The current system already uses a token family such as:
+
+- `--ui-bg`
+- `--ui-fg`
+- `--ui-fg-muted`
+- `--ui-surface`
+- `--ui-surface-hover`
+- `--ui-border`
+- `--ui-primary`
+- `--ui-accent`
+- `--ui-secondary`
+- `--ui-critical`
+- `--ui-success`
+- `--ui-warning`
+- `--ui-info`
+- `--ui-tonal-secondary`
+- `--ui-tonal-tertiary`
+- `--ui-ring`
+- `--ui-radius-md`
+- `--ui-shadow-sm`
+- `--ui-duration-normal`
+- `--ui-lift-hover`
+- `--ui-scale-active`
+
+These are acceptable as the starting contract.
+AI should prefer reusing and rationalizing these tokens before inventing new ones.
+A broader semantic model can be introduced gradually, but migration should be deliberate.
+The core token file also handles the default dark-mode remapping via `prefers-color-scheme`.
+
+## Visual direction
+
+Default design direction:
+
+- premium but not luxurious
+- technical but not sterile
+- calm, restrained, and modern
+- slightly soft geometry
+- strong dark mode support
+- subtle depth, not showy effects
+- polished indie product energy
+- close to modern product tooling, not generic Tailwind demo aesthetics
+
+When making visual choices, prefer restraint over novelty.
+
+## Styling rules
+
+1. Use semantic tokens or existing system tokens only.
+2. Never hard-code colors in primitives.
+3. Prefer class composition in `*.variants.ts` rather than giant inline strings in the SFC.
+4. Keep render templates small.
+5. Keep spacing and sizing aligned to shared scale.
+6. Use system radius tokens for silhouette consistency.
+7. Use system motion tokens for transitions.
+8. Focus treatment must be consistent across all interactive primitives.
+
+## API rules
+
+1. Prefer stable, small APIs.
+2. Keep naming consistent across primitives.
+3. Use `variant` consistently rather than inventing synonyms like `kind` or `appearance` unless absolutely required.
+4. Use `size` consistently.
+5. Use `disabled`, `invalid`, and `loading` consistently where relevant.
+6. Prefer composition over one-off prop sprawl.
+7. Support slots when they produce a cleaner API than multiple special props.
+
+## File conventions
+
+Each primitive should normally follow this structure:
+
+```txt
+Component/
+  Component.vue
+  Component.props.ts
+  Component.types.ts
+  Component.variants.ts
+  Component.spec.md
+```
+
+Responsibilities:
+
+- `Component.vue`: rendering and small computed composition only
+- `Component.props.ts`: prop definitions and defaults
+- `Component.types.ts`: exported unions and helper types
+- `Component.variants.ts`: size and variant maps, token-aware class composition
+- `Component.spec.md`: purpose, anatomy, props, variants, states, accessibility, usage
+
+## Ark UI policy
+
+Use Ark UI when it solves real interaction and accessibility complexity.
+
+Prefer Ark UI for:
+
+- Accordion
+- Checkbox
+- RadioGroup
+- Switch
+- Dialog
+- Popover
+- Tooltip
+- Menu
+- Tabs
+- Select
+- Combobox
+
+Do not force Ark UI for:
+
+- Button
+- Badge
+- Card
+- Spinner
+- Skeleton
+- Separator
+- Avatar wrapper
+
+## Required states for interactive primitives
+
+Where relevant, primitives must define and visually support:
+
+- default
+- hover
+- active
+- focus-visible
+- disabled
+- invalid
+- loading
+- open or selected where relevant
+
+## Forbidden AI behavior
+
+AI must not:
+
+- add new reusable UI under legacy `S*`
+- use raw Tailwind color utilities in primitives
+- invent arbitrary spacing or radius values ad hoc
+- create one-off variants without documenting the reason
+- bake theme differences into component logic when token mapping can solve it
+- copy legacy APIs line for line without evaluating their suitability for v2
+- place product-specific compositions into `src/primitives`
+
+## Output expectations
+
+When implementing or refactoring components, AI should:
+
+- state assumptions clearly
+- preserve good existing behavior when sensible
+- improve structure without unnecessary abstraction
+- keep code understandable for future agents
+- update the relevant spec file
+- update exports where appropriate
+- avoid unrelated churn

package/packages/ui/src/design-system/docs/PATTERN_RULES.md

@@ -0,0 +1,83 @@
+# PATTERN_RULES
+
+## Goal
+
+Patterns are reusable compositions built from primitives.
+They provide common UI arrangements without turning the core primitive layer into an app-specific dumping ground.
+
+## Current repo baseline
+
+`src/patterns/*` now exists as an architectural layer for shared compositions.
+`FormField` is the first established pattern and should be treated as the baseline for future pattern work.
+
+## What belongs in `src/patterns`
+
+Patterns should be:
+
+- composed from existing primitives
+- reusable across products or screens
+- somewhat opinionated in structure
+- still independent from business logic
+
+Examples:
+
+- FormField
+- SearchField
+- PageHeader
+- EmptyState
+- FilterBar
+- SidebarNav
+- AppShell
+- CommandMenu
+
+## What does not belong in `src/patterns`
+
+Do not place business or domain-specific components here.
+Examples of components that do not belong here:
+
+- billing-specific cards
+- product-only dashboard widgets
+- card reveal flows
+- domain-specific tables with business logic built in
+
+## Pattern rules
+
+1. patterns must be composed from primitives first
+2. patterns may add layout and grouping opinion
+3. patterns must still consume tokens, not raw visual values
+4. patterns may not bypass primitive behavior or accessibility contracts
+5. patterns should avoid owning business data transformations
+
+## API guidance
+
+Pattern APIs should remain relatively small.
+Patterns should expose only the knobs that are likely to matter broadly.
+If a pattern needs many highly product-specific switches, it is probably not a pattern.
+
+## Typical pattern structure
+
+```txt
+Pattern/
+  Pattern.vue
+  Pattern.types.ts
+  Pattern.spec.md
+```
+
+A `Pattern.variants.ts` file is optional if the pattern has enough variant logic to justify it.
+`src/patterns/index.ts` is part of the public pattern export surface and should be updated deliberately when new patterns are added.
+
+## Relationship to app code
+
+Applications should prefer using patterns where they fit.
+If a product needs a highly specific composition, build that in the product app rather than force it into the shared package.
+Legacy `S*` components may be inspected for composition ideas, but patterns must still be rebuilt from primitives rather than wrapped around legacy implementations.
+
+## Review checklist
+
+Before adding a pattern, confirm:
+
+- is it composed from primitives?
+- is it still product-agnostic?
+- does it belong above primitives but below app code?
+- is its API restrained?
+- is it documented?