@ternent/core 0.0.1

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

@@ -0,0 +1,258 @@
+# PRIMITIVE_RULES
+
+## Goal
+
+Primitives are the stable building blocks of `ternent-ui` v2.
+They must be easy for humans and AI agents to understand, extend, and compose.
+
+## Current repo baseline
+
+The current primitive layer is only partially aligned with this document.
+
+- `src/primitives/Button/*` established the first canonical template and should remain the baseline for future primitive structure.
+- `src/primitives/Accordion/*` is canonical, while `Accordian/*` remains a compatibility layer during migration.
+- `SplitButton/*` still exists from earlier work and should be reconciled with the newer primitive contract when touched.
+- `src/patterns/*` now exists for higher-level reusable compositions.
+- Primitive `*.spec.md` files now exist for the active v2 surface and must stay aligned with implementation changes.
+
+## Placement
+
+All new reusable low-level and mid-level components go in `src/primitives`.
+
+Do not place new reusable primitives in:
+
+- `src/components`
+- app-specific directories
+- ad hoc utility folders
+
+## Canonical file structure
+
+Each primitive should normally use this shape:
+
+```txt
+Component/
+  Component.vue
+  Component.props.ts
+  Component.types.ts
+  Component.variants.ts
+  Component.spec.md
+```
+
+This may be slightly simplified for very small components, but the default expectation is consistency.
+
+## File responsibilities
+
+### `Component.vue`
+
+Responsible for:
+
+- rendering structure
+- wiring props to classes and attributes
+- small computed class composition
+- slot rendering
+
+Avoid putting large variant maps directly in the SFC.
+
+### `Component.props.ts`
+
+Responsible for:
+
+- prop definitions
+- defaults
+- shared prop naming consistency
+
+### `Component.types.ts`
+
+Responsible for:
+
+- exported unions
+- helper types
+- public type surface
+
+### `Component.variants.ts`
+
+Responsible for:
+
+- base classes
+- size maps
+- variant maps
+- stateful class combinations
+- token-based class composition
+
+### `Component.spec.md`
+
+Responsible for:
+
+- purpose
+- category
+- anatomy
+- API
+- variants
+- sizes
+- states
+- accessibility requirements
+- examples
+- do and don’t guidance
+
+## API design rules
+
+1. prefer small APIs
+2. prefer consistent prop names across primitives
+3. prefer composition over one-off prop expansion
+4. do not import legacy API quirks without evaluating them
+5. use slots when they create a cleaner public surface
+6. expose only what is needed for stable usage
+
+## Shared prop conventions
+
+Use these consistently where relevant:
+
+- `variant`
+- `size`
+- `tone`
+- `disabled`
+- `invalid`
+- `loading`
+- `modelValue` for input-like primitives following Vue conventions
+- `as` only where polymorphism is genuinely needed
+
+Avoid drift such as:
+
+- `kind` vs `variant`
+- `error` vs `invalid`
+- `regular` vs `md`
+- `tiny` vs `xs`
+
+## Variant philosophy
+
+Use a restrained and repeatable vocabulary.
+
+Preferred baseline:
+
+- `solid`
+- `soft`
+- `outline`
+- `ghost`
+- `plain`
+
+Where a component needs a different axis based on existing repo reality, document it clearly.
+
+Because the current Button already uses variants like `primary`, `secondary`, and `critical`, the first refactor may preserve that vocabulary temporarily. If so, document it and avoid inventing yet another scheme in parallel.
+
+## Size philosophy
+
+Preferred baseline:
+
+- `sm`
+- `md`
+- `lg`
+
+Extra sizes such as `xs`, `xl`, or `micro` are allowed only when there is demonstrated usage.
+If a component uses extra sizes, the reason should be documented.
+
+## State requirements
+
+Interactive primitives should define and support relevant states.
+
+Common states:
+
+- default
+- hover
+- active
+- focus-visible
+- disabled
+- invalid
+- loading
+- selected
+- open
+
+Not every state applies to every primitive, but omission should be intentional.
+
+## Styling rules
+
+1. use semantic tokens only
+2. no raw Tailwind palette classes
+3. no arbitrary radius or spacing values
+4. no inline styles unless technically necessary and documented
+5. keep class logic centralized in `*.variants.ts` where practical
+6. keep the component silhouette consistent with the system
+
+## Composition rules
+
+Primitives should be:
+
+- composable
+- generic
+- not tied to app business logic
+- not tied to a single product layout
+
+If a component starts needing app-shell opinions or form grouping logic, consider making it a pattern instead.
+If the work belongs in `src/patterns`, create that layer intentionally rather than pretending it already exists.
+
+## Slots
+
+Use slots when they improve flexibility without bloating the prop API.
+
+Common slot use cases:
+
+- leading or trailing adornments
+- icon areas
+- content override areas
+- label or description composition in pattern-level components
+
+Avoid creating a prop for every possible visual arrangement when a slot is cleaner.
+
+## Accessibility expectations
+
+All primitives must meet the accessibility contract defined in `ACCESSIBILITY_RULES.md`.
+Where Ark UI is used, rely on it correctly rather than partially reimplementing behavior.
+
+## Spec requirement
+
+Every primitive should have a `Component.spec.md` file.
+This is not optional documentation fluff.
+It is part of the AI contract.
+
+Current repo note: this requirement is now satisfied for the active v2 primitive surface, so future primitive changes should update the relevant spec file instead of letting it drift.
+
+The spec should describe:
+
+- purpose
+- anatomy
+- props
+- emitted events if relevant
+- slots
+- variants
+- sizes
+- states
+- accessibility
+- token usage
+- examples
+
+## Export rules
+
+Every primitive added to `src/primitives` must also be reviewed for export in `src/primitives/index.ts`.
+Exports should be deliberate and stable.
+When adjusting existing primitives, account for the current exported surface, including `Button`, `SplitButton`, and the misspelled `Accordian` exports.
+
+## Refactor policy for legacy equivalents
+
+If a legacy `S*` component exists:
+
+- inspect it for behavior and usage reference only
+- do not port line by line
+- identify whether the v2 version should be a primitive or a pattern
+- preserve useful behavior but redesign the API if needed
+
+## Review checklist
+
+Before a primitive is considered ready, confirm:
+
+- it lives in `src/primitives`
+- it follows the canonical file shape
+- it uses tokens only
+- it has a documented API
+- it has relevant states
+- it is not leaking app logic
+- it is exported intentionally
+- it has a spec file

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

@@ -0,0 +1,235 @@
+# TOKEN_RULES
+
+## Goal
+
+Tokens are the contract that makes multi-theme support, visual consistency, and AI-driven implementation possible.
+
+Primitives must consume tokens, not raw visual values.
+
+## Token layers
+
+Use three conceptual layers.
+
+### 1. Raw tokens
+
+Raw tokens represent palette and scale values.
+These are theme authoring values, not component consumption values.
+
+Examples:
+
+- raw color values in theme files
+- scale values for radius, shadow, duration, spacing
+
+Raw tokens are allowed inside theme definitions and token generation logic.
+Primitives should not consume them directly.
+
+### 2. System semantic tokens
+
+These are the tokens primitives should consume.
+In this repo, the existing `--ui-*` tokens are already acting as the semantic layer.
+
+Existing examples include:
+
+- `--ui-bg`
+- `--ui-fg`
+- `--ui-fg-muted`
+- `--ui-surface`
+- `--ui-surface-hover`
+- `--ui-border`
+- `--ui-primary`
+- `--ui-on-primary`
+- `--ui-primary-muted`
+- `--ui-primary-hover`
+- `--ui-primary-active`
+- `--ui-accent`
+- `--ui-on-accent`
+- `--ui-secondary`
+- `--ui-on-secondary`
+- `--ui-critical`
+- `--ui-on-critical`
+- `--ui-success`
+- `--ui-on-success`
+- `--ui-warning`
+- `--ui-on-warning`
+- `--ui-info`
+- `--ui-on-info`
+- `--ui-tonal-secondary`
+- `--ui-tonal-tertiary`
+- `--ui-ring`
+- `--ui-glow-primary`
+- `--ui-radius-md`
+- `--ui-shadow-sm`
+- `--ui-duration-normal`
+- `--ui-ease-out`
+- `--ui-lift-hover`
+- `--ui-scale-active`
+
+These are acceptable as the current canonical consumption layer.
+
+Compatibility aliases also exist where needed, for example the `--ui-danger*` aliases that currently map to the `--ui-critical*` family.
+
+### 3. Optional component aliases
+
+Component aliases may be introduced sparingly when a primitive has a stable, repeated need that is too specific for the general semantic layer.
+
+Examples:
+
+- `--button-bg-primary`
+- `--input-border-default`
+- `--card-surface-default`
+
+Avoid component aliases unless the general token model cannot express the need cleanly.
+
+## Current repo strategy
+
+Do not perform a giant token rewrite first.
+Use the existing `--ui-*` family as the active semantic contract.
+Improve coverage and naming gradually.
+
+That means:
+
+- reuse the current token family wherever possible
+- expand carefully when a real gap appears
+- only rename tokens when the system meaning becomes meaningfully clearer
+- treat `src/design-system/tokens.css` as the current source of truth for the active semantic contract
+- preserve the current light/dark remapping behavior, which is defined in the core token file using `prefers-color-scheme`
+
+## Consumption rules
+
+Primitives must:
+
+1. consume existing `--ui-*` tokens or approved new semantic tokens only
+2. never hard-code hex, rgb, hsl, oklch, or named colors
+3. never use Tailwind palette utilities like `bg-zinc-900` or `text-red-500`
+4. never introduce arbitrary motion or radius values without updating the token contract
+5. prefer semantic token combinations over one-off visual hacks
+
+## Allowed primitive usage examples
+
+Good:
+
+- `bg-[var(--ui-primary)]`
+- `text-[var(--ui-on-primary)]`
+- `rounded-[var(--ui-radius-md)]`
+- `shadow-[var(--ui-shadow-sm)]`
+- `duration-[var(--ui-duration-normal)]`
+- `focus-visible:ring-[var(--ui-ring)]`
+
+Bad:
+
+- `bg-purple-700`
+- `text-zinc-100`
+- `rounded-[13px]`
+- `duration-150`
+- `shadow-[0_8px_30px_rgba(0,0,0,0.18)]` unless the shadow token is added first
+
+## Minimal semantic categories to preserve
+
+Even if token names evolve, the system should continue to support these semantic roles.
+
+### Base and text
+
+- canvas background
+- primary foreground
+- muted foreground
+- inverse foreground where needed
+
+### Surfaces
+
+- surface
+- surface hover
+- border
+- tonal surfaces
+
+### Interactive accents
+
+- primary
+- on primary
+- primary muted
+- primary hover
+- primary active
+
+### Feedback tones
+
+- critical
+- success
+- warning
+- info
+- corresponding “on” colors and muted or hover states where relevant
+
+### Utility tokens
+
+- focus ring
+- radii
+- shadows
+- durations
+- easing
+- interaction lift or active scale if retained
+
+## Adding a new token
+
+A new token may be added only when all of the following are true:
+
+1. a real component need exists
+2. the need cannot be expressed cleanly with current tokens
+3. the token has a clear semantic meaning
+4. it can be themed consistently across all supported themes
+5. the addition is documented in both token docs and affected components
+
+## Updating themes
+
+When a new semantic token is added:
+
+1. define it in the base token layer
+2. add it to every supported theme or ensure it safely falls back
+3. verify both light and dark behavior if relevant
+4. update any generated theme outputs if the build pipeline requires it
+
+AI must not add a new token in only one theme.
+
+## Token naming guidance
+
+Prefer names that describe role, not appearance.
+
+Prefer:
+
+- `--ui-surface`
+- `--ui-primary`
+- `--ui-fg-muted`
+- `--ui-ring`
+
+Avoid:
+
+- `--ui-purple`
+- `--ui-dark-border`
+- `--ui-button-green`
+
+If a name includes a component, it should only be because the token is a deliberate component alias.
+
+## Migration guidance
+
+Because the repo already has a working token family, migration should be staged.
+
+### Good migration work
+
+- replacing hard-coded values with existing `--ui-*` tokens
+- expanding missing states using current tokens
+- rationalizing inconsistent use of `surface`, `tonal`, and `primary` roles
+- preserving existing compatibility aliases until the consuming surface is deliberately migrated
+- introducing missing utility tokens with documentation
+
+### Bad migration work
+
+- renaming many tokens at once without a real need
+- introducing a second semantic vocabulary in parallel without a plan
+- forcing every primitive to adopt a new naming model before the token layer is stable
+
+## Review checklist
+
+Before merging token-related changes, confirm:
+
+- does the primitive use tokens only?
+- is the token meaning clear?
+- does the token work across all themes?
+- is the token documented?
+- is the change incremental rather than disruptive?

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

@@ -0,0 +1,68 @@
+# VISUAL_DIRECTION
+
+## Design intent
+
+`ternent-ui` should feel:
+
+- premium but not luxurious
+- technical but not sterile
+- calm, restrained, and modern
+- slightly soft in geometry
+- dense enough for serious app interfaces
+- polished in dark mode
+- quietly expressive rather than loud
+
+## Current repo baseline
+
+This visual direction should be applied through the existing semantic token system, not through one-off component styling.
+The active token contract already includes surface, border, accent, feedback, shadow, radius, duration, easing, and interaction-motion tokens.
+Legacy `S*` styling is not the visual standard for new primitive work.
+
+## Benchmark energy
+
+Aim closer to:
+
+- Stripe-level restraint
+- Vercel-level clarity
+- HeroUI-level polish in component finish
+
+Avoid:
+
+- generic Tailwind demo aesthetics
+- over-glassy or over-neumorphic effects
+- heavy gradients as a default surface strategy
+- toy-like radii and novelty motion
+
+## Surface model
+
+- canvas should feel quiet
+- surfaces should separate subtly from the canvas
+- interactive controls should read clearly from their container
+- elevation should be visible but restrained
+- borders should support structure without looking muddy
+
+## Shape model
+
+- controls should have consistent silhouette language
+- radius should feel modern and deliberate
+- default geometry should be rounded, not playful
+
+## Motion model
+
+- fast
+- subtle
+- purposeful
+- no decorative bounce
+- motion should support comprehension, not spectacle
+
+## Content density
+
+Default density should support real product work.
+Not cramped, not oversized.
+Aim for a professional app density that still feels breathable.
+
+## Theme strategy
+
+Multiple branded themes are a feature, but the system should still feel like one family.
+Theme changes should alter mood, not break structural consistency.
+The current default light/dark behavior comes from token remapping in the core token file, and future theme work should preserve that contract.