{"_id":"@aid-on/design-system","name":"@aid-on/design-system","dist-tags":{"latest":"0.1.1"},"versions":{"0.1.1":{"name":"@aid-on/design-system","version":"0.1.1","description":"Aid-On Design System - Design tokens and utilities for Qwik applications","type":"module","main":"./dist/index.js","module":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"import":"./dist/index.js","types":"./dist/index.d.ts"},"./tokens":{"import":"./dist/tokens/index.js","types":"./dist/tokens/index.d.ts"},"./colors":{"import":"./dist/tokens/colors.js","types":"./dist/tokens/colors.d.ts"},"./utils":{"import":"./dist/utils/index.js","types":"./dist/utils/index.d.ts"},"./css":"./dist/styles/tokens.css"},"scripts":{"build":"tsc && npm run build:css","build:css":"node scripts/generate-css.mjs","typecheck":"tsc --noEmit","test":"vitest run","test:watch":"vitest","dev":"tsc --watch"},"peerDependencies":{"@builder.io/qwik":"^1.11.0"},"devDependencies":{"@builder.io/qwik":"^1.11.0","@types/node":"^20.10.5","typescript":"^5.7.2","vitest":"^2.1.8"},"keywords":["design-system","design-tokens","qwik","colors","theming","aid-on"],"author":{"name":"Aid-On"},"license":"MIT","_id":"@aid-on/design-system@0.1.1","_nodeVersion":"20.19.6","_npmVersion":"10.8.2","dist":{"integrity":"sha512-z590hZ4mrZdetlpx8NtcxR1K/YIWo/pSP3lAoCvlqHmcfL0RgFa4iaA4z4j2yieelClTftNIP2Cxpkxy7jxUcw==","shasum":"d2cb4f0ffeb6dc0d871550340b3299dd4fc8c74f","tarball":"https://registry.npmjs.org/@aid-on/design-system/-/design-system-0.1.1.tgz","fileCount":19,"unpackedSize":45147,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIFASRErc4kbIA6VTrH52oyN1xQeur6E9C7owiydoTHwAAiEAi317jLubDFU7WNIiMUZg/0WfjUShML/zbdLeFtomeAk="}]},"_npmUser":{"name":"aid-on","email":"hiromi.motodera@aid-on.org"},"directories":{},"maintainers":[{"name":"aid-on","email":"hiromi.motodera@aid-on.org"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/design-system_0.1.1_1771435125873_0.9754034922453014"},"_hasShrinkwrap":false}},"time":{"created":"2026-02-18T17:18:45.760Z","0.1.1":"2026-02-18T17:18:46.023Z","modified":"2026-02-18T17:18:46.268Z"},"maintainers":[{"name":"aid-on","email":"hiromi.motodera@aid-on.org"}],"description":"Aid-On Design System - Design tokens and utilities for Qwik applications","keywords":["design-system","design-tokens","qwik","colors","theming","aid-on"],"author":{"name":"Aid-On"},"license":"MIT","readme":"# @aid-on/design-system\n\n<div align=\"center\">\n\n[![npm version](https://img.shields.io/npm/v/@aid-on/design-system.svg?style=flat-square&color=00DC82)](https://www.npmjs.com/package/@aid-on/design-system)\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.7-3178C6?style=flat-square&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)\n\n<br />\n\n<h3><b>design-system</b> - Design Tokens and Theming for Qwik Applications</h3>\n<p align=\"center\"><b>Consistent design, zero guesswork.</b><br/>A type-safe color token system with light/dark theme support built for @builder.io/qwik.</p>\n\n<br/>\n\n[**日本語**](./README.ja.md) | **English**\n\n<br/>\n\n</div>\n\n## Features\n\n- **Color Token System** - Structured color categories (surface, content, accent, semantic, status indicators) with light/dark variants\n- **Qwik Hooks** - `useTheme()` and `useColorPreference()` for reactive theme management\n- **CSS Variable Utilities** - `getCSSVariable()`, `colorClass()`, `colorStyle()` for flexible styling\n- **System Preference Detection** - Automatic `prefers-color-scheme` detection with live updates\n- **Generated CSS** - Pre-built CSS file with all token variables for direct import\n- **Sub-path Exports** - Import only what you need: `./tokens`, `./colors`, `./utils`, `./css`\n\n## Installation\n\n```bash\nnpm install @aid-on/design-system\n```\n\n**Peer dependency:**\n\n```bash\nnpm install @builder.io/qwik@^1.11.0\n```\n\n## Quick Start\n\n### 1. Initialize Theme\n\n```typescript\nimport { useTheme } from \"@aid-on/design-system\";\n\nexport const App = component$(() => {\n  const { theme, resolvedTheme, setTheme, toggleTheme } = useTheme();\n\n  return (\n    <div>\n      <p>Current theme: {resolvedTheme.value}</p>\n      <button onClick$={() => toggleTheme()}>Toggle Theme</button>\n      <button onClick$={() => setTheme(\"light\")}>Light</button>\n      <button onClick$={() => setTheme(\"dark\")}>Dark</button>\n      <button onClick$={() => setTheme(\"system\")}>System</button>\n    </div>\n  );\n});\n```\n\n### 2. Import CSS Tokens\n\n```typescript\n// Import generated CSS with all color variables\nimport \"@aid-on/design-system/css\";\n```\n\n### 3. Use Color Tokens in Styles\n\n```css\n.card {\n  background-color: var(--surface);\n  color: var(--content);\n  border-color: var(--accent-ghost);\n}\n\n.card:hover {\n  background-color: var(--surface-hover);\n}\n\n.error-message {\n  color: var(--red-4);\n  background-color: var(--red-7);\n}\n```\n\n## Color Categories\n\nThe token system is organized into semantic categories, each with light and dark theme variants:\n\n| Category | Tokens | Description |\n|----------|--------|-------------|\n| **Surface** | `--surface`, `--surface-elevated`, `--surface-hover`, `--surface-active`, `--surface-disabled` | Background colors for containers and layouts |\n| **Content** | `--content` through `--content-ghost` | Text and icon colors with 7 levels of emphasis |\n| **Accent** | `--accent` through `--accent-background` | Interactive element colors with 8 variants |\n| **Semantic** | `--white-1` through `--white-7` | Neutral white scale for overlays and borders |\n| **Caution Red** | `--red-1` through `--red-7` | Error and destructive action indicators |\n| **Alert Orange** | `--orange-1` through `--orange-7` | Warning and caution indicators |\n| **Success Green** | `--green-1` through `--green-7` | Success and confirmation indicators |\n| **Link Blue** | `--blue-1` through `--blue-7` | Links and informational indicators |\n\n## API Reference\n\n### Hooks\n\n#### `useTheme()`\n\nQwik hook for theme management with reactive state.\n\n```typescript\nconst { theme, resolvedTheme, setTheme, toggleTheme } = useTheme();\n```\n\n| Return | Type | Description |\n|--------|------|-------------|\n| `theme` | `Signal<Theme>` | Current theme setting (`'light'`, `'dark'`, or `'system'`) |\n| `resolvedTheme` | `Signal<'light' \\| 'dark'>` | Resolved theme after applying system preference |\n| `setTheme` | `(theme: Theme) => void` | Set theme and persist to localStorage |\n| `toggleTheme` | `() => void` | Toggle between light and dark |\n\n#### `useColorPreference()`\n\nHook to track system color scheme preference changes.\n\n```typescript\nconst preference = useColorPreference();\n// preference.value is 'light' or 'dark'\n```\n\n### Functions\n\n#### `initializeTheme()`\n\nInitialize theme from localStorage on app startup. Call this early in your app lifecycle.\n\n```typescript\nimport { initializeTheme } from \"@aid-on/design-system\";\n\nconst theme = initializeTheme(); // Returns current theme\n```\n\n#### `getCSSVariable(varName)`\n\nGet the computed value of a CSS variable at runtime.\n\n```typescript\nimport { getCSSVariable } from \"@aid-on/design-system\";\n\nconst surfaceColor = getCSSVariable(\"--surface\");\n```\n\n#### `colorClass(base, variant?, state?)`\n\nGenerate BEM-style class names for components.\n\n```typescript\nimport { colorClass } from \"@aid-on/design-system\";\n\ncolorClass(\"btn\");                          // \"btn\"\ncolorClass(\"btn\", \"primary\");               // \"btn btn--primary\"\ncolorClass(\"btn\", \"primary\", \"hover\");      // \"btn btn--primary btn--hover\"\ncolorClass(\"btn\", undefined, \"disabled\");   // \"btn btn--disabled\"\n```\n\n**Variants:** `'primary'`, `'secondary'`, `'accent'`, `'ghost'`, `'error'`, `'warning'`, `'success'`, `'info'`\n\n**States:** `'hover'`, `'active'`, `'disabled'`\n\n#### `colorStyle(fg?, bg?, border?)`\n\nGenerate inline style objects with CSS variable support.\n\n```typescript\nimport { colorStyle } from \"@aid-on/design-system\";\n\n// CSS variable names are automatically wrapped in var()\ncolorStyle(\"--content\", \"--surface\");\n// { color: \"var(--content)\", backgroundColor: \"var(--surface)\" }\n\n// Raw color values pass through unchanged\ncolorStyle(\"#333\", \"#fff\", \"#ccc\");\n// { color: \"#333\", backgroundColor: \"#fff\", borderColor: \"#ccc\" }\n```\n\n### Token Functions\n\n#### `getAllColorTokens(theme?)`\n\nGet all color tokens as a flat array for a given theme.\n\n```typescript\nimport { getAllColorTokens } from \"@aid-on/design-system/tokens\";\n\nconst lightTokens = getAllColorTokens(\"light\");\nconst darkTokens = getAllColorTokens(\"dark\");\n```\n\n#### `getColorByVariable(varName, theme?)`\n\nLook up a color value by its CSS variable name.\n\n```typescript\nimport { getColorByVariable } from \"@aid-on/design-system/tokens\";\n\nconst color = getColorByVariable(\"--surface\", \"light\"); // \"#6C4FEA\"\n```\n\n#### `generateColorCSSVariables(theme?)`\n\nGenerate CSS custom properties string for a theme.\n\n```typescript\nimport { generateColorCSSVariables } from \"@aid-on/design-system/tokens\";\n\nconst css = generateColorCSSVariables(\"dark\");\n// :root[data-theme=\"dark\"] { --surface: #6C4FEA; ... }\n```\n\n## Sub-path Exports\n\n```typescript\n// Everything\nimport { colors, useTheme, colorStyle } from \"@aid-on/design-system\";\n\n// Tokens only (no Qwik dependency)\nimport { colors, getAllColorTokens, getColorByVariable } from \"@aid-on/design-system/tokens\";\n\n// Colors directly\nimport { colors, ColorSystem } from \"@aid-on/design-system/colors\";\n\n// Utilities (requires Qwik)\nimport { useTheme, getCSSVariable, colorClass } from \"@aid-on/design-system/utils\";\n\n// CSS file\nimport \"@aid-on/design-system/css\";\n```\n\n## Types\n\n```typescript\nimport type {\n  ColorToken,      // { name: string; value: string; description: string }\n  ColorCategory,   // { light: ColorToken[]; dark: ColorToken[] }\n  ColorSystem,     // Full color system with all categories\n  Theme,           // 'light' | 'dark' | 'system'\n} from \"@aid-on/design-system\";\n```\n\n## How Theming Works\n\n1. `useTheme()` sets `data-theme` attribute on `<html>` and applies CSS variables inline\n2. Theme preference is persisted to `localStorage` under the key `aid-on-theme`\n3. When set to `'system'`, the hook listens to `prefers-color-scheme` media query changes\n4. CSS variables are applied directly to `document.documentElement.style`, so they override any stylesheet defaults\n\n## License\n\nMIT\n","readmeFilename":"README.md","_rev":"1-a2b611887f1be43b6a52e7fff53c8ccb"}