@sublimee/tokens 0.1.1 → 0.1.10

package/AI_INDEX.md

@@ -0,0 +1,48 @@
+# @sublimee/tokens AI Index
+
+Token-efficient entry point for AI agents reading the installed npm package.
+
+## Use This Package For
+
+- semantic theme vocabulary,
+- color, spacing, radius, shadow, and motion tokens,
+- type-safe token-name references.
+
+## First Move
+
+```tsx
+import "@sublimee/tokens/tokens.css";
+```
+
+## Core Rule
+
+Tokens describe purpose, not appearance.
+
+Prefer semantic names like:
+- `surface-0`
+- `text-primary`
+- `interactive-accent`
+
+## Primary Surfaces
+
+- [src/tokens.css](./src/tokens.css) for the token values
+- [src/index.ts](./src/index.ts) for exported token-name types
+- [README.md](./README.md) for usage guidance
+
+## Typical Next Step
+
+Override semantic custom properties instead of rewriting component styles:
+
+```css
+:root {
+  --sublime-color-interactive-accent: #ec4899;
+  --sublime-radius-button: 9999px;
+}
+```
+
+## Non-Goals
+
+Do not assume:
+- this package provides UI components,
+- hardcoded brand colors should replace semantic token usage,
+- dark mode should be solved separately from the token system.

package/README.md

@@ -1,369 +1,98 @@
 # @sublimee/tokens
 
-The semantic design token system for Sublime. Define your aesthetic once, use it everywhere.
+AI-first package doc for the Sublime semantic token layer.
 
-## Installation
+If you are an AI agent reading the installed npm package directly, start with [AI_INDEX.md](./AI_INDEX.md).
 
-```bash
-pnpm add @sublimee/tokens
-```
+## Use This Package When
 
-## Quick Start
+- you need the shared semantic design vocabulary,
+- you want to theme Sublime components,
+- you want stable color and motion names instead of hardcoded aesthetics.
 
-```css
-/* In your app's global CSS */
-@import "@sublimee/tokens";
-
-/* Override with your brand (optional) */
-:root {
-  --sublime-color-interactive-accent: #ec4899;
-  --sublime-radius-button: 9999px;
-}
-```
+## First Move
 
 ```tsx
-// Use in components
-<button className="bg-[var(--sublime-color-surface-1)] text-[var(--sublime-color-text-primary)]">
-  Click me
-</button>
+import "@sublimee/tokens/tokens.css";
 ```
 
----
-
-## Philosophy
-
-**"Describe purpose, not appearance."**
-
-Traditional approaches hardcode values:
-```css
-/* Bad: Hardcoded, breaks in dark mode */
-.button { background: white; color: black; }
-```
+or
 
-Sublime uses semantic tokens:
 ```css
-/* Good: Adapts to theme context */
-.button { 
-  background: var(--sublime-color-surface-1); 
-  color: var(--sublime-color-text-primary); 
-}
-```
-
-Tokens describe **what something is**, not **how it looks**:
-- `surface-1` = elevated container (could be white in light mode, gray-900 in dark)
-- `text-primary` = main text (could be black in light mode, white in dark)
-- `interactive-accent` = brand color for CTAs (your pink, their blue, etc.)
-
----
-
-## Token Categories
-
-### Colors (`--sublime-color-*`)
-
-#### Surface Colors
-Background colors for containers, cards, pages.
-
-| Token | Purpose |
-|-------|---------|
-| `--sublime-color-surface-0` | Page background (base layer) |
-| `--sublime-color-surface-1` | Elevated surfaces (cards, modals) |
-| `--sublime-color-surface-2` | Higher elevation |
-| `--sublime-color-surface-inset` | Depressed surfaces (inputs, wells) |
-
-Each has hover/active states:
-- `--sublime-color-surface-1-hover`
-- `--sublime-color-surface-1-active`
-
-#### Text Colors
-Content colors by emphasis level.
-
-| Token | Purpose |
-|-------|---------|
-| `--sublime-color-text-primary` | Headings, important text |
-| `--sublime-color-text-secondary` | Body text, descriptions |
-| `--sublime-color-text-muted` | Captions, placeholders |
-| `--sublime-color-text-disabled` | Disabled state |
-| `--sublime-color-text-accent` | Links, highlights |
-
-Each has an `-inverse` variant for use on dark surfaces.
-
-#### Border Colors
-Dividers, outlines, input borders.
-
-| Token | Purpose |
-|-------|---------|
-| `--sublime-color-border-primary` | Main borders |
-| `--sublime-color-border-secondary` | Subtle dividers |
-| `--sublime-color-border-accent` | Focused/active states |
-| `--sublime-color-border-error` | Error states |
-
-#### Interactive Colors
-Buttons, links, controls.
-
-| Token | Purpose |
-|-------|---------|
-| `--sublime-color-interactive-primary` | High-emphasis actions |
-| `--sublime-color-interactive-secondary` | Medium-emphasis actions |
-| `--sublime-color-interactive-ghost` | Low-emphasis actions |
-| `--sublime-color-interactive-accent` | Brand color actions |
-
-Each has hover, active, and text variants:
-- `--sublime-color-interactive-primary-hover`
-- `--sublime-color-interactive-primary-active`
-- `--sublime-color-interactive-primary-text`
-
-#### Status Colors
-Feedback states.
-
-| Token | Purpose |
-|-------|---------|
-| `--sublime-color-status-error` | Errors, destructive actions |
-| `--sublime-color-status-warning` | Warnings, cautions |
-| `--sublime-color-status-success` | Success, confirmations |
-| `--sublime-color-status-info` | Information, tips |
-
-Each has hover and background variants.
-
-#### Focus & Selection
-
-| Token | Purpose |
-|-------|---------|
-| `--sublime-color-focus-ring` | Keyboard focus indicator |
-| `--sublime-color-focus-ring-offset` | Ring background |
-| `--sublime-color-selection-bg` | Text selection background |
-| `--sublime-color-selection-text` | Selected text color |
-
-#### Overlays
-
-| Token | Purpose |
-|-------|---------|
-| `--sublime-color-overlay-light` | Light backdrops |
-| `--sublime-color-overlay-dark` | Dark backdrops |
-| `--sublime-color-overlay-scrim` | Modal overlays |
-
-### Spacing (`--sublime-space-*`)
-
-Base-4 spacing scale:
-
-```
---sublime-space-1: 0.25rem   (4px)
---sublime-space-2: 0.5rem    (8px)
---sublime-space-3: 0.75rem   (12px)
---sublime-space-4: 1rem      (16px)
---sublime-space-6: 1.5rem    (24px)
---sublime-space-8: 2rem      (32px)
-```
-
-Component-specific aliases:
-- `--sublime-space-button-x`
-- `--sublime-space-button-y`
-- `--sublime-space-card-padding`
-
-### Shadows (`--sublime-shadow-*`)
-
-Elevation system:
-
-```
---sublime-shadow-xs   (subtle)
---sublime-shadow-sm   (cards)
---sublime-shadow-md   (elevated cards)
---sublime-shadow-lg   (modals)
---sublime-shadow-xl   (dialogs)
-```
-
-Component-specific aliases:
-- `--sublime-shadow-button`
-- `--sublime-shadow-card`
-- `--sublime-shadow-focus-ring`
-
-### Border Radius (`--sublime-radius-*`)
-
-```
---sublime-radius-sm    (4px)
---sublime-radius-md    (6px)
---sublime-radius-lg    (8px)
---sublime-radius-xl    (12px)
---sublime-radius-2xl   (16px)
---sublime-radius-full  (pill/circle)
-```
-
-Component-specific aliases:
-- `--sublime-radius-button`
-- `--sublime-radius-card`
-- `--sublime-radius-input`
-
-### Typography (`--sublime-font-*`)
-
-```
---sublime-font-family-sans
---sublime-font-family-mono
-
---sublime-font-size-xs   (12px)
---sublime-font-size-sm   (14px)
---sublime-font-size-md   (16px)
---sublime-font-size-lg   (18px)
---sublime-font-size-xl   (20px)
-
---sublime-font-weight-medium
---sublime-font-weight-semibold
---sublime-font-weight-bold
-
---sublime-line-height-tight
---sublime-line-height-normal
---sublime-line-height-relaxed
-```
-
-### Animation (`--sublime-duration-*`, `--sublime-ease-*`)
-
-```
---sublime-duration-fast: 100ms
---sublime-duration-normal: 150ms
---sublime-duration-slow: 200ms
-
---sublime-ease-out: cubic-bezier(0, 0, 0.2, 1)
---sublime-ease-spring: cubic-bezier(0.34, 1.56, 0.64, 1)
+@import "@sublimee/tokens/tokens.css";
 ```
 
-Component-specific aliases:
-- `--sublime-transition-button`
-- `--sublime-transition-color`
-- `--sublime-transition-transform`
-
----
+## Core Rule
 
-## Dark Mode
+Tokens describe purpose, not appearance.
 
-All color tokens have dark variants that activate via:
+Prefer:
+- `surface-0`
+- `text-primary`
+- `interactive-accent`
 
-1. `.dark` class on ancestor
-2. `[data-theme="dark"]` attribute on ancestor
-3. `prefers-color-scheme: dark` media query (fallback)
-
-```css
-/* Automatic dark mode */
-<html class="dark">
-  <body class="bg-[var(--sublime-color-surface-0)]">
-    <!-- All components render in dark mode -->
-  </body>
-</html>
-```
+Avoid:
+- hardcoded brand colors inside reusable library work
+- aesthetic names that do not explain role
 
----
+## Primary Token Families
 
-## Customization
+- `--sublime-color-*`
+- `--sublime-space-*`
+- `--sublime-shadow-*`
+- `--sublime-radius-*`
+- `--sublime-font-*`
+- `--sublime-duration-*`
+- `--sublime-ease-*`
+- `--sublime-transition-*`
 
-### Method 1: Override Specific Tokens
+## Typical Use
 
 ```css
-@import "@sublimee/tokens";
+@import "@sublimee/tokens/tokens.css";
 
 :root {
-  /* Your brand pink */
   --sublime-color-interactive-accent: #ec4899;
-  --sublime-color-interactive-accent-hover: #db2777;
-  
-  /* Pill-shaped buttons */
   --sublime-radius-button: 9999px;
-  
-  /* Softer shadows */
-  --sublime-shadow-md: 0 4px 12px -2px rgb(0 0 0 / 0.08);
-}
-
-.dark {
-  /* Lighter accent in dark mode for contrast */
-  --sublime-color-interactive-accent: #f472b6;
 }
 ```
 
-### Method 2: Complete Theme Override
-
-Replace all tokens for a completely custom aesthetic:
-
-```css
-@import "@sublimee/tokens";  /* Import defaults first */
-
-:root {
-  /* Then override everything */
-  --sublime-color-surface-0: #fafaf9;
-  --sublime-color-surface-1: #ffffff;
-  /* ... etc */
-}
-```
-
-### Method 3: Component-Specific Overrides
-
-```css
-/* Only change buttons */
-.btn-custom {
-  --sublime-color-interactive-primary: #your-color;
-}
-```
-
----
-
-## Usage with Tailwind
-
-### Arbitrary Values
-
 ```tsx
-<button className="bg-[var(--sublime-color-surface-1)]">
-  Click
-</button>
-```
-
-### Custom Utilities (Recommended)
-
-Add to your Tailwind config:
-
-```js
-// tailwind.config.js
-module.exports = {
-  theme: {
-    extend: {
-      colors: {
-        sublime: {
-          surface: {
-            0: 'var(--sublime-color-surface-0)',
-            1: 'var(--sublime-color-surface-1)',
-          },
-          text: {
-            primary: 'var(--sublime-color-text-primary)',
-          },
-        },
-      },
-    },
-  },
-};
-```
-
-Then use:
-
-```tsx
-<button className="bg-sublime-surface-1 text-sublime-text-primary">
-  Click
+<button
+  className="bg-[var(--sublime-color-surface-1)] text-[var(--sublime-color-text-primary)]"
+>
+  Click me
 </button>
 ```
 
----
+## Task Routing
 
-## Token Reference Table
+### Brand customization
 
-See [TOKENS.md](./TOKENS.md) for the complete token reference.
+Override semantic custom properties instead of rewriting component styles.
 
----
+### Dark mode
 
-## TypeScript
+Use the token system's theme handling through:
+- `.dark` on an ancestor,
+- `[data-theme="dark"]` on an ancestor,
+- or system preference as fallback.
 
-Token names can be typed for IDE autocomplete:
+### Type-safe token references
 
 ```tsx
-import type { SublimeColorToken, SublimeSpaceToken } from '@sublimee/tokens';
-
-// Token names as string literals for type safety
-const color: SublimeColorToken = '--sublime-color-surface-1';
+import type {
+  SublimeColorToken,
+  SublimeSpaceToken,
+  SublimeToken,
+} from "@sublimee/tokens";
 ```
 
----
+## Role In The System
+
+This package does not provide UI on its own.
+
+Its job is to let the UI packages ship strong defaults that stay customizable without drifting away from the system.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sublimee/tokens",
-  "version": "0.1.1",
+  "version": "0.1.10",
   "description": "Semantic design tokens for Sublime",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -8,7 +8,8 @@
   "style": "./dist/tokens.css",
   "files": [
     "dist",
-    "src"
+    "src",
+    "AI_INDEX.md"
   ],
   "exports": {
     ".": {