@dezkareid/components 0.0.0 → 1.0.0

package/dist/react/Button/index.d.ts

@@ -0,0 +1,6 @@
+import type { ButtonHTMLAttributes } from 'react';
+import type { ButtonProps } from '../../shared/types/button';
+type Props = ButtonProps & ButtonHTMLAttributes<HTMLButtonElement>;
+export declare function Button({ variant, size, disabled, children, className, ...rest }: Props): import("react/jsx-runtime").JSX.Element;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/react/Button/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/react/Button/index.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,OAAO,CAAC;AAElD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAG7D,KAAK,KAAK,GAAG,WAAW,GAAG,oBAAoB,CAAC,iBAAiB,CAAC,CAAC;AAEnE,wBAAgB,MAAM,CAAC,EACrB,OAAmB,EACnB,IAAW,EACX,QAAgB,EAChB,QAAQ,EACR,SAAS,EACT,GAAG,IAAI,EACR,EAAE,KAAK,2CAgBP"}

package/dist/react/Button/index.js

@@ -0,0 +1,10 @@
+import { jsx } from 'react/jsx-runtime';
+import cx from '../../_virtual/index.js';
+import styles from '../../css/button.module.css.js';
+
+function Button({ variant = 'primary', size = 'md', disabled = false, children, className, ...rest }) {
+    return (jsx("button", { className: cx(styles.button, styles[`button--${variant}`], styles[`button--${size}`], disabled && styles['button--disabled'], className), disabled: disabled, ...rest, children: children }));
+}
+
+export { Button };
+//# sourceMappingURL=index.js.map

package/dist/react/Button/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":["../../../src/react/Button/index.tsx"],"sourcesContent":[null],"names":["_jsx"],"mappings":";;;;AAOM,SAAU,MAAM,CAAC,EACrB,OAAO,GAAG,SAAS,EACnB,IAAI,GAAG,IAAI,EACX,QAAQ,GAAG,KAAK,EAChB,QAAQ,EACR,SAAS,EACT,GAAG,IAAI,EACD,EAAA;AACN,IAAA,QACEA,GAAA,CAAA,QAAA,EAAA,EACE,SAAS,EAAE,EAAE,CACX,MAAM,CAAC,MAAM,EACb,MAAM,CAAC,WAAW,OAAO,CAAA,CAAE,CAAC,EAC5B,MAAM,CAAC,CAAA,QAAA,EAAW,IAAI,EAAE,CAAC,EACzB,QAAQ,IAAI,MAAM,CAAC,kBAAkB,CAAC,EACtC,SAAS,CACV,EACD,QAAQ,EAAE,QAAQ,EAAA,GACd,IAAI,YAEP,QAAQ,EAAA,CACF;AAEb;;;;"}

package/dist/react/Card/index.d.ts

@@ -0,0 +1,6 @@
+import type { HTMLAttributes } from 'react';
+import type { CardProps } from '../../shared/types/card';
+type Props = CardProps & HTMLAttributes<HTMLDivElement>;
+export declare function Card({ elevation, children, className, ...rest }: Props): import("react/jsx-runtime").JSX.Element;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/react/Card/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/react/Card/index.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,OAAO,CAAC;AAE5C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAGzD,KAAK,KAAK,GAAG,SAAS,GAAG,cAAc,CAAC,cAAc,CAAC,CAAC;AAExD,wBAAgB,IAAI,CAAC,EAAE,SAAoB,EAAE,QAAQ,EAAE,SAAS,EAAE,GAAG,IAAI,EAAE,EAAE,KAAK,2CAMjF"}

package/dist/react/Card/index.js

@@ -0,0 +1,10 @@
+import { jsx } from 'react/jsx-runtime';
+import cx from '../../_virtual/index.js';
+import styles from '../../css/card.module.css.js';
+
+function Card({ elevation = 'raised', children, className, ...rest }) {
+    return (jsx("div", { className: cx(styles.card, styles[`card--${elevation}`], className), ...rest, children: children }));
+}
+
+export { Card };
+//# sourceMappingURL=index.js.map

package/dist/react/Card/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":["../../../src/react/Card/index.tsx"],"sourcesContent":[null],"names":["_jsx"],"mappings":";;;;AAOM,SAAU,IAAI,CAAC,EAAE,SAAS,GAAG,QAAQ,EAAE,QAAQ,EAAE,SAAS,EAAE,GAAG,IAAI,EAAS,EAAA;IAChF,QACEA,GAAA,CAAA,KAAA,EAAA,EAAK,SAAS,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,SAAS,SAAS,CAAA,CAAE,CAAC,EAAE,SAAS,CAAC,EAAA,GAAM,IAAI,EAAA,QAAA,EAC/E,QAAQ,EAAA,CACL;AAEV;;;;"}

package/dist/react/Tag/index.d.ts

@@ -0,0 +1,6 @@
+import type { HTMLAttributes } from 'react';
+import type { TagProps } from '../../shared/types/tag';
+type Props = TagProps & HTMLAttributes<HTMLSpanElement>;
+export declare function Tag({ variant, children, className, ...rest }: Props): import("react/jsx-runtime").JSX.Element;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/react/Tag/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/react/Tag/index.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,OAAO,CAAC;AAE5C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAGvD,KAAK,KAAK,GAAG,QAAQ,GAAG,cAAc,CAAC,eAAe,CAAC,CAAC;AAExD,wBAAgB,GAAG,CAAC,EAAE,OAAmB,EAAE,QAAQ,EAAE,SAAS,EAAE,GAAG,IAAI,EAAE,EAAE,KAAK,2CAM/E"}

package/dist/react/Tag/index.js

@@ -0,0 +1,10 @@
+import { jsx } from 'react/jsx-runtime';
+import cx from '../../_virtual/index.js';
+import styles from '../../css/tag.module.css.js';
+
+function Tag({ variant = 'default', children, className, ...rest }) {
+    return (jsx("span", { className: cx(styles.tag, styles[`tag--${variant}`], className), ...rest, children: children }));
+}
+
+export { Tag };
+//# sourceMappingURL=index.js.map

package/dist/react/Tag/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":["../../../src/react/Tag/index.tsx"],"sourcesContent":[null],"names":["_jsx"],"mappings":";;;;AAOM,SAAU,GAAG,CAAC,EAAE,OAAO,GAAG,SAAS,EAAE,QAAQ,EAAE,SAAS,EAAE,GAAG,IAAI,EAAS,EAAA;IAC9E,QACEA,GAAA,CAAA,MAAA,EAAA,EAAM,SAAS,EAAE,EAAE,CAAC,MAAM,CAAC,GAAG,EAAE,MAAM,CAAC,QAAQ,OAAO,CAAA,CAAE,CAAC,EAAE,SAAS,CAAC,EAAA,GAAM,IAAI,EAAA,QAAA,EAC5E,QAAQ,EAAA,CACJ;AAEX;;;;"}

package/dist/react/ThemeToggle/index.d.ts

@@ -0,0 +1,2 @@
+export declare function ThemeToggle(): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=index.d.ts.map

package/dist/react/ThemeToggle/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/react/ThemeToggle/index.tsx"],"names":[],"mappings":"AAMA,wBAAgB,WAAW,4CA6B1B"}

package/dist/react/ThemeToggle/index.js

@@ -0,0 +1,25 @@
+import { jsx } from 'react/jsx-runtime';
+import { useState, useEffect } from 'react';
+import cx from '../../_virtual/index.js';
+import { getInitialTheme, applyTheme, persistTheme } from '../../shared/js/theme.js';
+import styles from '../../css/theme-toggle.module.css.js';
+
+function ThemeToggle() {
+    const [theme, setTheme] = useState('light');
+    useEffect(() => {
+        const initial = getInitialTheme();
+        setTheme(initial);
+        applyTheme(initial);
+    }, []);
+    function toggle() {
+        const next = theme === 'light' ? 'dark' : 'light';
+        setTheme(next);
+        applyTheme(next);
+        persistTheme(next);
+    }
+    const isDark = theme === 'dark';
+    return (jsx("button", { type: "button", className: cx(styles['theme-toggle'], isDark && styles['theme-toggle--dark']), onClick: toggle, "aria-label": isDark ? 'Switch to light mode' : 'Switch to dark mode', "aria-pressed": isDark, children: isDark ? 'Dark' : 'Light' }));
+}
+
+export { ThemeToggle };
+//# sourceMappingURL=index.js.map

package/dist/react/ThemeToggle/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":["../../../src/react/ThemeToggle/index.tsx"],"sourcesContent":[null],"names":["_jsx"],"mappings":";;;;;;SAMgB,WAAW,GAAA;IACzB,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,GAAG,QAAQ,CAAQ,OAAO,CAAC;IAElD,SAAS,CAAC,MAAK;AACb,QAAA,MAAM,OAAO,GAAG,eAAe,EAAE;QACjC,QAAQ,CAAC,OAAO,CAAC;QACjB,UAAU,CAAC,OAAO,CAAC;IACrB,CAAC,EAAE,EAAE,CAAC;AAEN,IAAA,SAAS,MAAM,GAAA;AACb,QAAA,MAAM,IAAI,GAAU,KAAK,KAAK,OAAO,GAAG,MAAM,GAAG,OAAO;QACxD,QAAQ,CAAC,IAAI,CAAC;QACd,UAAU,CAAC,IAAI,CAAC;QAChB,YAAY,CAAC,IAAI,CAAC;IACpB;AAEA,IAAA,MAAM,MAAM,GAAG,KAAK,KAAK,MAAM;IAE/B,QACEA,gBACE,IAAI,EAAC,QAAQ,EACb,SAAS,EAAE,EAAE,CAAC,MAAM,CAAC,cAAc,CAAC,EAAE,MAAM,IAAI,MAAM,CAAC,oBAAoB,CAAC,CAAC,EAC7E,OAAO,EAAE,MAAM,EAAA,YAAA,EACH,MAAM,GAAG,sBAAsB,GAAG,qBAAqB,EAAA,cAAA,EACrD,MAAM,YAEnB,MAAM,GAAG,MAAM,GAAG,OAAO,EAAA,CACnB;AAEb;;;;"}

package/dist/react/index.d.ts

@@ -0,0 +1,5 @@
+export { Button } from './Button/index';
+export { Tag } from './Tag/index';
+export { Card } from './Card/index';
+export { ThemeToggle } from './ThemeToggle/index';
+//# sourceMappingURL=index.d.ts.map

package/dist/react/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/react/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AACxC,OAAO,EAAE,GAAG,EAAE,MAAM,aAAa,CAAC;AAClC,OAAO,EAAE,IAAI,EAAE,MAAM,cAAc,CAAC;AACpC,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/react/index.js

@@ -0,0 +1,5 @@
+export { Button } from './Button/index.js';
+export { Tag } from './Tag/index.js';
+export { Card } from './Card/index.js';
+export { ThemeToggle } from './ThemeToggle/index.js';
+//# sourceMappingURL=index.js.map

package/dist/react/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;"}

package/dist/shared/js/theme.d.ts

@@ -0,0 +1,5 @@
+import type { Theme } from '../types/theme-toggle';
+export declare function getInitialTheme(): Theme;
+export declare function applyTheme(theme: Theme): void;
+export declare function persistTheme(theme: Theme): void;
+//# sourceMappingURL=theme.d.ts.map

package/dist/shared/js/theme.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"theme.d.ts","sourceRoot":"","sources":["../../../src/shared/js/theme.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,uBAAuB,CAAC;AAInD,wBAAgB,eAAe,IAAI,KAAK,CAOvC;AAED,wBAAgB,UAAU,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,CAG7C;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,CAG/C"}

package/dist/shared/js/theme.js

@@ -0,0 +1,22 @@
+const STORAGE_KEY = 'color-scheme';
+function getInitialTheme() {
+    if (typeof window === 'undefined')
+        return 'light';
+    const stored = localStorage.getItem(STORAGE_KEY);
+    if (stored === 'light' || stored === 'dark')
+        return stored;
+    return window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
+}
+function applyTheme(theme) {
+    if (typeof window === 'undefined')
+        return;
+    document.documentElement.setAttribute('color-scheme', theme);
+}
+function persistTheme(theme) {
+    if (typeof window === 'undefined')
+        return;
+    localStorage.setItem(STORAGE_KEY, theme);
+}
+
+export { applyTheme, getInitialTheme, persistTheme };
+//# sourceMappingURL=theme.js.map

package/dist/shared/js/theme.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"theme.js","sources":["../../../src/shared/js/theme.ts"],"sourcesContent":[null],"names":[],"mappings":"AAEA,MAAM,WAAW,GAAG,cAAc;SAElB,eAAe,GAAA;IAC7B,IAAI,OAAO,MAAM,KAAK,WAAW;AAAE,QAAA,OAAO,OAAO;IAEjD,MAAM,MAAM,GAAG,YAAY,CAAC,OAAO,CAAC,WAAW,CAAC;AAChD,IAAA,IAAI,MAAM,KAAK,OAAO,IAAI,MAAM,KAAK,MAAM;AAAE,QAAA,OAAO,MAAM;AAE1D,IAAA,OAAO,MAAM,CAAC,UAAU,CAAC,8BAA8B,CAAC,CAAC,OAAO,GAAG,MAAM,GAAG,OAAO;AACrF;AAEM,SAAU,UAAU,CAAC,KAAY,EAAA;IACrC,IAAI,OAAO,MAAM,KAAK,WAAW;QAAE;IACnC,QAAQ,CAAC,eAAe,CAAC,YAAY,CAAC,cAAc,EAAE,KAAK,CAAC;AAC9D;AAEM,SAAU,YAAY,CAAC,KAAY,EAAA;IACvC,IAAI,OAAO,MAAM,KAAK,WAAW;QAAE;AACnC,IAAA,YAAY,CAAC,OAAO,CAAC,WAAW,EAAE,KAAK,CAAC;AAC1C;;;;"}

package/dist/shared/types/button.d.ts

@@ -0,0 +1,8 @@
+export type ButtonVariant = 'primary' | 'secondary' | 'outline' | 'ghost' | 'success';
+export type ButtonSize = 'sm' | 'md' | 'lg' | 'small' | 'medium' | 'large';
+export interface ButtonProps {
+    variant?: ButtonVariant;
+    size?: ButtonSize;
+    disabled?: boolean;
+}
+//# sourceMappingURL=button.d.ts.map

package/dist/shared/types/button.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"button.d.ts","sourceRoot":"","sources":["../../../src/shared/types/button.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,aAAa,GAAG,SAAS,GAAG,WAAW,GAAG,SAAS,GAAG,OAAO,GAAG,SAAS,CAAC;AACtF,MAAM,MAAM,UAAU,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,OAAO,GAAG,QAAQ,GAAG,OAAO,CAAC;AAE3E,MAAM,WAAW,WAAW;IAC1B,OAAO,CAAC,EAAE,aAAa,CAAC;IACxB,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB"}

package/dist/shared/types/card.d.ts

@@ -0,0 +1,5 @@
+export type CardElevation = 'flat' | 'raised';
+export interface CardProps {
+    elevation?: CardElevation;
+}
+//# sourceMappingURL=card.d.ts.map

package/dist/shared/types/card.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"card.d.ts","sourceRoot":"","sources":["../../../src/shared/types/card.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,QAAQ,CAAC;AAE9C,MAAM,WAAW,SAAS;IACxB,SAAS,CAAC,EAAE,aAAa,CAAC;CAC3B"}

package/dist/shared/types/tag.d.ts

@@ -0,0 +1,5 @@
+export type TagVariant = 'default' | 'success' | 'danger';
+export interface TagProps {
+    variant?: TagVariant;
+}
+//# sourceMappingURL=tag.d.ts.map

package/dist/shared/types/tag.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tag.d.ts","sourceRoot":"","sources":["../../../src/shared/types/tag.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,UAAU,GAAG,SAAS,GAAG,SAAS,GAAG,QAAQ,CAAC;AAE1D,MAAM,WAAW,QAAQ;IACvB,OAAO,CAAC,EAAE,UAAU,CAAC;CACtB"}

package/dist/shared/types/theme-toggle.d.ts

@@ -0,0 +1,4 @@
+export type Theme = 'light' | 'dark';
+export interface ThemeToggleProps {
+}
+//# sourceMappingURL=theme-toggle.d.ts.map

package/dist/shared/types/theme-toggle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"theme-toggle.d.ts","sourceRoot":"","sources":["../../../src/shared/types/theme-toggle.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,KAAK,GAAG,OAAO,GAAG,MAAM,CAAC;AAErC,MAAM,WAAW,gBAAgB;CAEhC"}

package/dist/vue/index.d.ts

@@ -0,0 +1,5 @@
+export { default as Button } from './Button/index.vue';
+export { default as Tag } from './Tag/index.vue';
+export { default as Card } from './Card/index.vue';
+export { default as ThemeToggle } from './ThemeToggle/index.vue';
+//# sourceMappingURL=index.d.ts.map

package/dist/vue/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/vue/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,IAAI,MAAM,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,EAAE,OAAO,IAAI,GAAG,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,EAAE,OAAO,IAAI,IAAI,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,EAAE,OAAO,IAAI,WAAW,EAAE,MAAM,yBAAyB,CAAC"}

package/done/2026-03-03-design-system-components/osddt.plan.md

@@ -0,0 +1,233 @@
+# Implementation Plan: Design System Components
+
+## Architecture Overview
+
+### Directory Structure
+
+Framework-specific components are grouped by framework. CSS and shared logic live in a top-level `shared/` folder, keeping styling and utilities decoupled from any framework.
+
+```
+src/
+  css/
+    button.module.css       # Button BEM + OOCSS classes
+    tag.module.css          # Tag BEM + OOCSS classes
+    card.module.css         # Card BEM + OOCSS classes
+    theme-toggle.module.css # ThemeToggle BEM + OOCSS classes
+  shared/
+    js/
+      theme.ts                # ThemeToggle logic (read/write localStorage, apply color-scheme)
+    types/
+      button.ts               # ButtonProps interface
+      tag.ts                  # TagProps interface
+      card.ts                 # CardProps interface
+      theme-toggle.ts         # ThemeToggleProps interface
+  react/
+    Button/
+      index.tsx
+      index.test.tsx
+    Tag/
+      index.tsx
+      index.test.tsx
+    Card/
+      index.tsx
+      index.test.tsx
+    ThemeToggle/
+      index.tsx
+      index.test.tsx
+    index.ts                  # Barrel: exports all React components
+  astro/
+    Button/
+      index.astro
+    Tag/
+      index.astro
+    Card/
+      index.astro
+    ThemeToggle/
+      index.astro
+    index.ts                  # Barrel: exports all Astro components
+  vue/
+    Button/
+      index.vue
+    Tag/
+      index.vue
+    Card/
+      index.vue
+    ThemeToggle/
+      index.vue
+    index.ts                  # Barrel: exports all Vue components
+```
+
+### Styling Strategy
+
+- **CSS Modules** for component-scoped styles, located in `src/css/`.
+- **BEM** for class naming within each module: block (`button`), element (`button__label`), modifier (`button--primary`, `button--sm`, `button--disabled`).
+- **OOCSS** to separate structural responsibility from skin responsibility:
+  - *Structure classes* define layout, sizing, spacing, and display behaviour (e.g. `.button`, `.card`).
+  - *Skin classes* define colour, border, shadow, and typography (e.g. `.button--primary`, `.tag--success`, `.card--raised`).
+  - Framework files compose both structure and skin classes together.
+- All colour, spacing, and font values use CSS custom properties from `@dezkareid/design-tokens`.
+- Semantic tokens (`--color-background-primary`, `--color-text-primary`, etc.) are used exclusively — no raw hex/px values.
+
+### Theming
+
+- The `color-scheme` attribute on `<html>` drives light/dark switching.
+- `ThemeToggle` is the only component that reads/writes theme state. All other components are passive consumers of semantic tokens.
+- `ThemeToggle` uses `localStorage` (key: `color-scheme`) for persistence and falls back to `prefers-color-scheme`.
+
+### TypeScript
+
+- Shared prop interfaces/types are defined in `src/shared/types/<component>.ts` and imported by all three framework implementations.
+- Strict typing; no `any`.
+
+### Testing
+
+- React implementations only (as per spec).
+- Vitest + React Testing Library.
+- Tests cover: rendering variants, disabled states, slot/children content, ThemeToggle localStorage and OS-preference behaviour.
+
+### Entry Points
+
+The package will expose three sub-path exports:
+- `@dezkareid/components/react` → all React components
+- `@dezkareid/components/astro` → all Astro components
+- `@dezkareid/components/vue` → all Vue components
+
+`package.json` `exports` field will be configured accordingly.
+
+---
+
+## Implementation Phases
+
+### Phase 1 — Package Setup
+
+**Goal**: Establish the build infrastructure, folder layout, and entry points before writing any component code.
+
+- Configure `package.json` with `exports` for `react/`, `astro/`, and `vue/` sub-paths.
+- Create the full directory skeleton: `src/css/`, `src/shared/js/`, `src/shared/types/`, `src/react/`, `src/astro/`, `src/vue/`.
+- Create barrel `index.ts` files for each framework entry point (`src/react/index.ts`, `src/astro/index.ts`, `src/vue/index.ts`).
+- Verify that `@dezkareid/design-tokens` is available as a dependency and that its CSS token file can be imported from `src/css/`.
+- Set up Vitest config (if not present) targeting `src/react/**/*.test.tsx`.
+
+### Phase 2 — Button Component
+
+**Goal**: Implement the Button component across all three frameworks with full variant, size, and disabled support.
+
+- Define `ButtonProps` in `src/shared/types/button.ts`: `variant: 'primary' | 'secondary'`, `size: 'sm' | 'md' | 'lg'`, `disabled?: boolean`, `children/slot`.
+- Write `src/css/button.module.css` using BEM + OOCSS:
+  - **Structure**: `.button` — `display: inline-flex`, `align-items: center`, `cursor: pointer`, `border: none`, `border-radius`.
+  - **Structure modifiers** (size): `.button--sm`, `.button--md`, `.button--lg` — vary `padding` and `font-size` via spacing/font tokens.
+  - **Skin modifiers** (variant): `.button--primary` — `background-color: var(--color-primary)`, `color: var(--color-text-inverse)`; `.button--secondary` — `background-color: transparent`, `border: 1px solid var(--color-primary)`, `color: var(--color-primary)`.
+  - **State modifier**: `.button--disabled` — reduced opacity, `cursor: not-allowed`, `pointer-events: none`.
+- Implement `src/react/Button/index.tsx` — renders `<button>`, composes BEM classes from CSS module, passes through native button props.
+- Implement `src/astro/Button/index.astro`.
+- Implement `src/vue/Button/index.vue`.
+- Write `src/react/Button/index.test.tsx`: renders each variant, renders each size, disabled prevents click, accessible role.
+
+### Phase 3 — Tag Component
+
+**Goal**: Implement the Tag component across all three frameworks with semantic colour variants and children support.
+
+- Define `TagProps` in `src/shared/types/tag.ts`: `variant: 'default' | 'success' | 'danger'`, `children/slot`.
+- Write `src/css/tag.module.css` using BEM + OOCSS:
+  - **Structure**: `.tag` — `display: inline-flex`, `align-items: center`, `border-radius`, `padding: var(--spacing-4) var(--spacing-8)`, `font-size: var(--font-size-100)`.
+  - **Skin modifiers** (variant): `.tag--default` — `background-color: var(--color-background-secondary)`, `color: var(--color-text-primary)`; `.tag--success` — `background-color: var(--color-success)`, `color: var(--color-text-inverse)`; `.tag--danger` — `background-color: var(--color-base-red-500)`, `color: var(--color-text-inverse)`. *(Note: propose `--color-danger` semantic token for the design-tokens package.)*
+- Implement `src/react/Tag/index.tsx` — renders a `<span>`, composes BEM classes, accepts `children`.
+- Implement `src/astro/Tag/index.astro`.
+- Implement `src/vue/Tag/index.vue`.
+- Write `src/react/Tag/index.test.tsx`: renders each variant, renders slot/children content.
+
+### Phase 4 — Card Component
+
+**Goal**: Implement the Card component across all three frameworks with flat and raised elevation.
+
+- Define `CardProps` in `src/shared/types/card.ts`: `elevation?: 'flat' | 'raised'` (default: `'raised'`), `children/slot`.
+- Write `src/css/card.module.css` using BEM + OOCSS:
+  - **Structure**: `.card` — `display: block`, `border-radius`, `padding: var(--spacing-24)`, `width: 100%`.
+  - **Skin** (base): `.card` — `background-color: var(--color-background-secondary)`, `color: var(--color-text-primary)`.
+  - **Skin modifiers** (elevation): `.card--raised` — `box-shadow: 0 2px 8px rgba(0,0,0,0.12)` *(propose `--shadow-raised` token)*; `.card--flat` — no shadow.
+- Implement `src/react/Card/index.tsx` — renders a `<div>`, composes BEM classes, accepts `children`.
+- Implement `src/astro/Card/index.astro`.
+- Implement `src/vue/Card/index.vue`.
+- Write `src/react/Card/index.test.tsx`: renders children, applies correct elevation class.
+
+### Phase 5 — ThemeToggle Component
+
+**Goal**: Implement the ThemeToggle component across all three frameworks with localStorage persistence and OS preference fallback.
+
+- Define `ThemeToggleProps` in `src/shared/types/theme-toggle.ts`: no required props (self-contained stateful component).
+- Extract shared theme logic to `src/shared/js/theme.ts`:
+  - `getInitialTheme(): 'light' | 'dark'` — reads `localStorage.getItem('color-scheme')`; falls back to `window.matchMedia('(prefers-color-scheme: dark)').matches`.
+  - `applyTheme(theme: 'light' | 'dark'): void` — sets `document.documentElement.setAttribute('color-scheme', theme)`.
+  - `persistTheme(theme: 'light' | 'dark'): void` — writes to `localStorage`.
+  - All functions guard against `typeof window === 'undefined'` for SSR safety.
+- Write `src/css/theme-toggle.module.css` using BEM + OOCSS:
+  - **Structure**: `.theme-toggle` — `display: inline-flex`, `align-items: center`, `cursor: pointer`, `padding`, `border: none`.
+  - **Skin**: `.theme-toggle` — `background-color: transparent`, `color: var(--color-text-primary)`.
+  - **State modifier**: `.theme-toggle--dark` — visual indicator for dark mode active state.
+- Implement `src/react/ThemeToggle/index.tsx` — uses `useState` + `useEffect`, calls `src/shared/js/theme.ts` utilities.
+- Implement `src/astro/ThemeToggle/index.astro` — static markup + inline `<script>` that imports and calls `src/shared/js/theme.ts`.
+- Implement `src/vue/ThemeToggle/index.vue` — uses `ref` + `onMounted`, calls shared utilities.
+- Write `src/react/ThemeToggle/index.test.tsx`: initialises from `localStorage`, initialises from `prefers-color-scheme` when no stored value, toggles on click, persists to `localStorage`.
+
+### Phase 6 — Exports & Package Configuration
+
+**Goal**: Wire all components into the entry points and validate the exports map.
+
+- Update `src/react/index.ts` to re-export `Button`, `Tag`, `Card`, `ThemeToggle` from their respective sub-folders.
+- Update `src/astro/index.ts` to re-export Astro components.
+- Update `src/vue/index.ts` to re-export Vue components.
+- Update `package.json` `exports`:
+  ```json
+  {
+    "./react": "./src/react/index.ts",
+    "./astro": "./src/astro/index.ts",
+    "./vue": "./src/vue/index.ts"
+  }
+  ```
+- Verify build compiles without errors.
+
+### Phase 7 — Documentation
+
+**Goal**: Update `README.md` and `AGENTS.md` to reflect the new components.
+
+- Add installation note for `@dezkareid/design-tokens` CSS requirement.
+- Add usage examples for each component in each framework format.
+- Update `AGENTS.md` with component API summaries.
+
+---
+
+## Technical Dependencies
+
+| Dependency | Purpose | Already Present? |
+|---|---|---|
+| `@dezkareid/design-tokens` | CSS token variables | To verify |
+| `react` / `react-dom` | React runtime | Peer dep |
+| `vue` | Vue runtime | To add as peer dep |
+| `astro` | Astro runtime | To add as peer dep |
+| `vitest` | Test runner | To configure |
+| `@testing-library/react` | React test utilities | To configure |
+| `jsdom` | DOM environment for tests | To configure |
+| `typescript` | Type checking | To configure |
+
+---
+
+## Risks & Mitigations
+
+| Risk | Mitigation |
+|---|---|
+| Missing semantic tokens (e.g. `--color-danger`, `--shadow-raised`) | Use base tokens as fallback; add inline comments proposing new tokens to the design-tokens package |
+| CSS Modules not supported in Astro/Vue by default | Astro natively supports CSS Modules; Vue supports them via `<style module>` — both are straightforward |
+| `localStorage` access in SSR/Astro contexts | Wrap all `localStorage` access in `typeof window !== 'undefined'` guards; use `is:inline` or `client:load` in Astro |
+| ThemeToggle hydration flash (FOUC) | Emit an inline `<script>` that applies the theme before first paint (Astro strategy); React version uses `useEffect` which may flash — document as a known limitation |
+| Vue not yet configured as a peer dependency | Add `vue` peer dep to `package.json` in Phase 1 |
+
+---
+
+## Out of Scope
+
+- Icon library (no icon assets bundled with components).
+- Animation/transition system.
+- Loading state or icon-only Button variant.
+- Storybook or visual regression tooling.
+- SSR-optimised theme detection beyond the `<script>` injection approach.
+- Astro and Vue unit tests (React tests only, per spec).

package/done/2026-03-03-design-system-components/osddt.spec.md

@@ -0,0 +1,90 @@
+# Feature Specification: Design System Components
+
+## Overview
+
+Add four foundational UI components — **Button**, **Tag**, **Card**, and **ThemeToggle** — to the `@dezkareid/components` package. These components form the core building blocks of the personal design system, enabling consistent, accessible, and theme-aware UI across all surfaces that consume the package (React, Astro, Vue).
+
+Each component must ship in all three framework formats (React, Astro, Vue), use design tokens for all visual properties, and support light/dark theming automatically.
+
+---
+
+## Requirements
+
+### Button
+
+- Renders a clickable element that triggers an action.
+- Supports at least two visual variants: **primary** (filled) and **secondary** (outlined).
+- Supports a **disabled** state that prevents interaction and communicates non-interactivity visually.
+- Accepts a label via slot/children.
+- Must be keyboard-accessible and announce its role to assistive technologies.
+
+### Tag
+
+- Renders a small inline label used to categorise or annotate content.
+- Supports at least three semantic colour variants: **default**, **success**, and **danger**.
+- Is non-interactive (display only).
+- Text content is passed via slot/children.
+- Must be readable by assistive technologies (appropriate role/label).
+
+### Card
+
+- Renders a contained surface that groups related content.
+- Accepts arbitrary content via slot/children (title, body, actions).
+- Provides consistent internal spacing and a distinct background relative to the page.
+- Must be usable as a layout container with no fixed height.
+
+### ThemeToggle
+
+- Renders a toggle control that switches the active colour scheme between light and dark.
+- The current theme state is reflected visually (icon or label change).
+- Toggling persists the preference to `localStorage` under the key `color-scheme`.
+- On initial load, reads `localStorage` first; falls back to the OS `prefers-color-scheme` preference.
+- Theme is applied by setting `color-scheme` on the `<html>` element (`light` or `dark`).
+- Must be keyboard-accessible and communicate its current state to assistive technologies.
+
+---
+
+## Scope
+
+### In scope
+
+- React, Astro, and Vue implementations for all four components.
+- Design-token-driven styling (no hardcoded colour or spacing values).
+- Automatic light/dark theme support via CSS semantic tokens.
+- Accessible markup (keyboard navigation, ARIA roles/attributes where needed).
+- Mobile-first responsive behaviour.
+- Unit/integration tests for the React implementations.
+- TypeScript prop types/interfaces for all components.
+- Updated `README.md` and `AGENTS.md` with usage examples for each component.
+
+### Out of scope
+
+- Icon library integration (icons may be addressed as a follow-up).
+- Animation or transition systems.
+- Complex compound variants (e.g. icon-only Button, loading state).
+- Storybook or visual regression tooling.
+- Server-side rendering (SSR) specific configuration.
+
+---
+
+## Acceptance Criteria
+
+1. **Button** renders correctly in primary and secondary variants and is disabled when `disabled` is set.
+2. **Tag** renders in default, success, and danger variants using the correct semantic colour tokens.
+3. **Card** renders its children inside a visually distinct surface with consistent spacing.
+4. **ThemeToggle** switches the `color-scheme` attribute on `<html>` and persists the value to `localStorage`.
+5. **ThemeToggle** reads `localStorage` on mount and applies the stored value; if absent, applies the OS preference.
+6. All components pass accessibility checks (keyboard focus, ARIA) without errors.
+7. All components render correctly in both light and dark modes using semantic tokens only.
+8. React implementations have passing unit tests.
+9. Each component is exported from the appropriate entry point (`react/`, `astro/`, `vue/`).
+10. `README.md` includes import and usage examples for all four components.
+
+---
+
+## Decisions
+
+1. **Button sizes**: Button will support three size variants — small, medium, and large — via a `size` prop.
+2. **Tag dismissibility**: Tag remains display-only with no close action. It must accept arbitrary content via slot/children (not just a plain text string).
+3. **Card elevation**: Card will support two elevation levels — **flat** (no shadow) and **raised** (with shadow) — via an `elevation` prop.
+4. **ThemeToggle framework scope**: ThemeToggle will ship in all three framework formats (React, Astro, Vue), consistent with the other components.