@codenhub/styles 0.0.3 → 0.1.0

package/llms.txt

@@ -0,0 +1,26 @@
+# @codenhub/styles
+
+> CSS-only Codenhub design tokens, reset, typography, layout and content utilities, component classes, native-element styling, and Tailwind CSS v4 source entrypoints.
+
+Use compiled entrypoints for ready-to-import CSS or `/tw` entrypoints in a
+Tailwind CSS v4 build. The package has no JavaScript behavior. Supported behavior
+is the surface documented in public docs and demonstrated by the playground.
+
+## Documentation
+
+- [Documentation](./docs/index.md): Primary entrypoint — what the package is, what it does and does not do, and where to go next.
+- [README](./README.md): Installation, first use, requirements, and stability notes.
+- [Setup](./docs/setup.md): Installation, entrypoint/import-path reference, configuration, and requirements.
+- [Concepts](./docs/concepts.md): The three-axis model, the token system, and theme-selector precedence.
+- [Usage](./docs/usage/index.md): Composing, theming, customizing, aesthetics, and each component family.
+  - [Composing](./docs/usage/composing.md): Combining axes, presentation, the component axis matrix, and elevation.
+  - [Theming](./docs/usage/theming.md): Color, intent, and foundation token reference.
+  - [Customizing](./docs/usage/customizing.md): Presentation, material, and aesthetic token reference.
+  - [Aesthetics](./docs/usage/aesthetics.md): Each shipped aesthetic and its documented exceptions.
+  - [Buttons](./docs/usage/buttons.md)
+  - [Forms](./docs/usage/forms.md)
+  - [Feedback](./docs/usage/feedback.md)
+  - [Tooltips](./docs/usage/tooltips.md)
+  - [Content and layout](./docs/usage/content-and-layout.md): Layout helpers, content chips/tables, surfaces, and typography utilities.
+- [Integrating](./docs/integrating/index.md): Wiring the stylesheet into Next.js, Vue, Svelte, Astro, or a Tailwind CSS v4 build.
+- [Accessibility](./docs/accessibility.md): CSS accessibility behavior and consumer responsibilities.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codenhub/styles",
-  "version": "0.0.3",
+  "version": "0.1.0",
   "private": false,
   "description": "CSS-only Codenhub design tokens, base styles, and composable UI helper classes.",
   "homepage": "https://github.com/codenhub/codenhub/tree/main/packages/styles",
@@ -11,35 +11,89 @@
     "directory": "packages/styles"
   },
   "files": [
-    "docs",
     "dist",
-    "src"
+    "NOTICE",
+    "README.md",
+    "docs",
+    "llms.txt",
+    "llms-full.txt"
   ],
   "type": "module",
   "exports": {
-    ".": "./dist/index.css",
-    "./theme": "./dist/theme.css",
-    "./components": "./dist/components.css",
-    "./tw": "./src/index.css",
-    "./tw/theme": "./src/theme.css",
-    "./tw/components": "./src/components/index.css",
-    "./tw/surface": "./src/components/surface.css",
-    "./tw/button": "./src/components/button.css",
-    "./tw/form": "./src/components/form.css",
-    "./tw/feedback": "./src/components/feedback.css",
-    "./tw/loader": "./src/components/loader.css",
-    "./tw/tooltip": "./src/components/tooltip.css",
-    "./tw/utilities": "./src/utilities.css"
+    ".": {
+      "style": "./dist/index.css",
+      "import": "./dist/index.css",
+      "default": "./dist/index.css"
+    },
+    "./theme": {
+      "style": "./dist/theme.css",
+      "import": "./dist/theme.css",
+      "default": "./dist/theme.css"
+    },
+    "./components": {
+      "style": "./dist/components.css",
+      "import": "./dist/components.css",
+      "default": "./dist/components.css"
+    },
+    "./aesthetics": {
+      "style": "./dist/aesthetics/index.css",
+      "import": "./dist/aesthetics/index.css",
+      "default": "./dist/aesthetics/index.css"
+    },
+    "./aesthetics/neobrutalism": {
+      "style": "./dist/aesthetics/neobrutalism.css",
+      "import": "./dist/aesthetics/neobrutalism.css",
+      "default": "./dist/aesthetics/neobrutalism.css"
+    },
+    "./aesthetics/glass": {
+      "style": "./dist/aesthetics/glass.css",
+      "import": "./dist/aesthetics/glass.css",
+      "default": "./dist/aesthetics/glass.css"
+    },
+    "./aesthetics/pixel": {
+      "style": "./dist/aesthetics/pixel.css",
+      "import": "./dist/aesthetics/pixel.css",
+      "default": "./dist/aesthetics/pixel.css"
+    },
+    "./aesthetics/chunky-tile": {
+      "style": "./dist/aesthetics/chunky-tile.css",
+      "import": "./dist/aesthetics/chunky-tile.css",
+      "default": "./dist/aesthetics/chunky-tile.css"
+    },
+    "./tw": "./dist/tw/index.css",
+    "./tw/theme": "./dist/tw/theme.css",
+    "./tw/components": "./dist/tw/components/index.css",
+    "./tw/surface": "./dist/tw/components/surface.css",
+    "./tw/button": "./dist/tw/components/button.css",
+    "./tw/form": "./dist/tw/components/form.css",
+    "./tw/feedback": "./dist/tw/components/feedback.css",
+    "./tw/loader": "./dist/tw/components/loader.css",
+    "./tw/tooltip": "./dist/tw/components/tooltip.css",
+    "./tw/reset": "./dist/tw/reset.css",
+    "./tw/native": "./dist/tw/native.css",
+    "./tw/typography": "./dist/tw/typography.css",
+    "./tw/utilities": "./dist/tw/utilities/index.css",
+    "./tw/aesthetics": "./dist/tw/aesthetics/index.css",
+    "./tw/aesthetics/neobrutalism": "./dist/tw/aesthetics/neobrutalism.css",
+    "./tw/aesthetics/glass": "./dist/tw/aesthetics/glass.css",
+    "./tw/aesthetics/pixel": "./dist/tw/aesthetics/pixel.css",
+    "./tw/aesthetics/chunky-tile": "./dist/tw/aesthetics/chunky-tile.css",
+    "./native": {
+      "style": "./dist/native.css",
+      "import": "./dist/native.css",
+      "default": "./dist/native.css"
+    }
   },
   "publishConfig": {
     "access": "public"
   },
   "devDependencies": {
-    "@playwright/test": "^1.57.0",
-    "@tailwindcss/cli": "^4.3.0",
-    "@types/node": "^25.9.1",
-    "tailwindcss": "^4.3.0",
-    "typescript": "^6.0.3"
+    "@playwright/test": "^1.61.1",
+    "@tailwindcss/cli": "^4.3.2",
+    "@types/node": "^26.1.0",
+    "tailwindcss": "^4.3.2",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.10"
   },
   "peerDependencies": {
     "tailwindcss": ">=4.0.0"
@@ -49,18 +103,28 @@
       "optional": true
     }
   },
+  "codenhub": {
+    "docs": {
+      "label": "StyleKit",
+      "status": "active"
+    }
+  },
   "scripts": {
-    "dev": "node ./scripts/dev.js",
-    "build": "pnpm build:styles",
-    "build:styles": "tailwindcss -i ./src/index.css -o ./dist/index.css --minify && tailwindcss -i ./src/theme.css -o ./dist/theme.css --minify && tailwindcss -i ./src/components/index.css -o ./dist/components.css --minify",
+    "clean": "node -e \"fs.rmSync('dist', { recursive: true, force: true })\"",
+    "dev": "pnpm --filter=@codenhub/styles-dev dev",
+    "debug": "pnpm build && pnpm --filter=@codenhub/styles-debug dev",
+    "demo": "pnpm build && pnpm --filter=@codenhub/styles-demo dev",
+    "build": "pnpm clean && pnpm build:styles && pnpm build:aesthetics && pnpm build:tw",
+    "build:styles": "tailwindcss -i ./src/index.css -o ./dist/index.css --minify && tailwindcss -i ./src/theme.css -o ./dist/theme.css --minify && tailwindcss -i ./src/components/index.css -o ./dist/components.css --minify && tailwindcss -i ./src/native.css -o ./dist/native.css --minify",
+    "build:aesthetics": "tailwindcss -i ./src/aesthetics/index.css -o ./dist/aesthetics/index.css --minify && tailwindcss -i ./src/aesthetics/neobrutalism.css -o ./dist/aesthetics/neobrutalism.css --minify && tailwindcss -i ./src/aesthetics/glass.css -o ./dist/aesthetics/glass.css --minify && tailwindcss -i ./src/aesthetics/pixel.css -o ./dist/aesthetics/pixel.css --minify && tailwindcss -i ./src/aesthetics/chunky-tile.css -o ./dist/aesthetics/chunky-tile.css --minify",
+    "build:tw": "node -e \"import('node:fs').then(fs => fs.cpSync('src', 'dist/tw', { recursive: true }))\"",
     "status:npm": "npm view @codenhub/styles version dist-tags time --json && npm dist-tag ls @codenhub/styles && npm access get status @codenhub/styles",
-    "status:pack": "npm pack --dry-run",
-    "test": "pnpm typecheck && pnpm test:build && pnpm test:visual",
-    "test:build": "pnpm build && pnpm test:build:vanilla && pnpm test:build:tw",
-    "test:build:tw": "tailwindcss -i ./tests/build/index.css -o ./tests/build/output.css --minify",
-    "test:build:vanilla": "tailwindcss -i ./tests/vanilla/index.css -o ./tests/vanilla/output.css --minify",
-    "test:visual": "playwright test",
-    "test:watch": "playwright test --ui",
-    "typecheck": "tsc --project tsconfig.json --noEmit"
+    "status:pack": "npm pack --dry-run --ignore-scripts",
+    "test": "vitest run",
+    "test:browser": "playwright test",
+    "test:browser:watch": "playwright test --ui",
+    "test:coverage": "pnpm test",
+    "test:watch": "vitest --watch",
+    "typecheck": "tsc -b"
   }
 }

package/docs/classes.md

@@ -1,198 +0,0 @@
-# @codenhub/styles Classes
-
-**Status:** IMPLEMENTED
-**Last updated:** 2026-06-18
-**Scope:** Public helper classes for `@codenhub/styles`.
-
-Helper classes are CSS-only. They provide presentation and state styling, not semantics or behavior.
-
-## Layout
-
-`.stack`, `.cluster`, and `.auto-grid` are `@utility` classes. They are available in both the full stylesheet and the Tailwind source entrypoints, and participate in Tailwind's JIT pipeline.
-
-| Class              | Purpose                                                        |
-| ------------------ | -------------------------------------------------------------- |
-| `.stack`           | Vertical flex stack using `--layout-stack-gap`.                |
-| `.stack.tight`     | Smaller stack gap.                                             |
-| `.stack.loose`     | Larger stack gap.                                              |
-| `.cluster`         | Wrapping horizontal flex cluster using `--layout-cluster-gap`. |
-| `.cluster.between` | Cluster with `space-between` alignment.                        |
-| `.auto-grid`       | Responsive auto-fit grid using `--layout-grid-min`.            |
-
-## Surfaces
-
-| Class          | Purpose                                       |
-| -------------- | --------------------------------------------- |
-| `.empty-state` | Centered empty-state layout with muted color. |
-
-## Buttons
-
-Use `.btn` with one optional intent class, one optional presentation class, optional size class, and optional state.
-
-Intent classes map color tokens into button tone slots. Presentation classes own how those slots become background, text, border, hover, and spinner styles.
-
-Intent classes:
-
-| Class                               | Meaning                        |
-| ----------------------------------- | ------------------------------ |
-| `.primary`                          | Primary action.                |
-| `.secondary`                        | Secondary/accent action.       |
-| `.success`                          | Successful or positive action. |
-| `.warning`                          | Warning/caution action.        |
-| `.destructive`, `.danger`, `.error` | Destructive or error action.   |
-| `.info`                             | Informational action.          |
-
-Presentation and size classes:
-
-| Class                                                                  | Purpose                                                                       |
-| ---------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
-| `.out`                                                                 | Transparent button with intent readable-tone border and text.                 |
-| `.ghost`                                                               | Transparent button with intent readable-tone text and soft hover.             |
-| `.soft`                                                                | Low-emphasis filled button using intent subtle surface and strong text tones. |
-| `.pill`                                                                | Fully rounded button corners (`border-radius: 9999px`).                       |
-| `.fill` with `.out`                                                    | Filled hover treatment using intent color and contrast text.                  |
-| `.sm`                                                                  | Smaller button.                                                               |
-| `.lg`                                                                  | Larger button.                                                                |
-| `.icon`                                                                | Square icon button. Use an accessible name in HTML.                           |
-| `.loading`                                                             | Loading state. Hides text and shows CSS activity indicator.                   |
-| `.disabled`, `[disabled]`, `[aria-disabled="true"]`, `[data-disabled]` | Disabled styling.                                                             |
-
-Examples:
-
-```html
-<button class="btn primary">Primary</button>
-<button class="btn success out">Success outline</button>
-<button class="btn warning soft">Warning soft</button>
-<button class="btn destructive ghost">Danger ghost</button>
-<button class="btn icon primary" aria-label="Create">+</button>
-<button class="btn primary loading" disabled>Saving</button>
-```
-
-`.loading` is a state, not a color or presentation class. Prefer combining it with disabled behavior so users cannot trigger duplicate work. Loading buttons keep only opacity and transform transitions active so spinner and surface colors stay synchronized when theme tokens change.
-
-## Forms
-
-| Class or Selector                                                     | Purpose                             |
-| --------------------------------------------------------------------- | ----------------------------------- |
-| `.field`                                                              | Vertical field wrapper.             |
-| `.label`                                                              | Form label text.                    |
-| `.hint`                                                               | Secondary helper text.              |
-| `.error` inside `.field` except `.btn.error`, `.field-error`          | Destructive helper text.            |
-| `.ipt`                                                                | Input control styling.              |
-| `.textarea`                                                           | Textarea control styling.           |
-| `.select`                                                             | Select control styling.             |
-| `input[type="checkbox"].checkbox`                                     | Custom checkbox control styling.    |
-| `input[type="checkbox"].switch`                                       | Custom switch control styling.      |
-| `[aria-invalid="true"]` on controls                                   | Destructive border and focus color. |
-| `[disabled]`, `[aria-disabled="true"]`, `[data-disabled]` on controls | Disabled styling.                   |
-
-`.checkbox` and `.switch` accept the same intent classes as buttons to set the checked color:
-
-| Class                               | Meaning            |
-| ----------------------------------- | ------------------ |
-| _(default)_                         | Primary color.     |
-| `.success`                          | Success color.     |
-| `.warning`                          | Warning color.     |
-| `.destructive`, `.danger`, `.error` | Destructive color. |
-| `.info`                             | Info color.        |
-
-Example:
-
-```html
-<label class="field">
-  <span class="label">Email</span>
-  <input class="ipt" type="email" aria-invalid="true" aria-describedby="email-error" />
-  <span class="error" id="email-error">Enter a valid email.</span>
-</label>
-<label style="display: flex; gap: 0.5rem; align-items: center">
-  <input type="checkbox" class="checkbox success" />
-  <span>Accept terms</span>
-</label>
-<label style="display: flex; gap: 0.5rem; align-items: center">
-  <input type="checkbox" class="switch destructive" />
-  <span>Enable</span>
-</label>
-```
-
-`.progress` also accepts the same intent classes to color the fill bar:
-
-## Feedback
-
-| Class       | Purpose                                                             |
-| ----------- | ------------------------------------------------------------------- |
-| `.alert`    | Inline feedback surface.                                            |
-| `.icon`     | Subclass of `.alert`. Adds a corresponding intent icon and padding. |
-| `.badge`    | Compact status pill.                                                |
-| `.ai`       | Low-level activity indicator. Applies CSS masking.                  |
-| `.loader`   | Standalone inline loader. Composes `.ai` with visual styles.        |
-| `.skeleton` | Ambient loading placeholder.                                        |
-| `.progress` | Progress track. Fill element uses `--progress-value`.               |
-
-Feedback helpers accept the same intent classes as buttons: `.success`, `.warning`, `.destructive`, `.danger`, `.error`, and `.info`.
-
-`.icon` is a subclass of `.alert`. When applied as `.alert.icon`, it increases the left padding and adds an embedded SVG icon matching the alert's intent (success, warning, error, info).
-
-`.badge` also accepts presentation variant classes:
-
-| Class    | Purpose                                                                            |
-| -------- | ---------------------------------------------------------------------------------- |
-| _(none)_ | Default. Tinted surface, intent-colored text, subtle intent-tinted border.         |
-| `.flat`  | Filled with the intent color; uses contrast text. Border matches the intent color. |
-| `.soft`  | Tinted surface and intent-colored text with no border (border is transparent).     |
-
-Examples:
-
-```html
-<div class="alert success" role="status">Saved successfully.</div>
-<div class="alert success icon" role="status">Saved successfully with icon.</div>
-<span class="badge warning">Queued</span>
-<span class="badge success flat">Live</span>
-<span class="badge info soft">Draft</span>
-<span class="loader" aria-hidden="true"></span>
-<span class="loader dots-wave" aria-hidden="true"></span>
-<div class="progress" aria-label="Upload progress"><span style="--progress-value: 64%"></span></div>
-<div class="progress success" aria-label="Upload progress"><span style="--progress-value: 64%"></span></div>
-```
-
-## Tooltips
-
-| Class or Attribute                 | Purpose                                                      |
-| ---------------------------------- | ------------------------------------------------------------ |
-| `.tooltip`                         | Tooltip host. Uses `data-tooltip` as pseudo-element content. |
-| `.tooltip.tooltip-icon`            | Circular icon-style tooltip host.                            |
-| `[data-tooltip-position="top"]`    | Positions tooltip above host.                                |
-| `[data-tooltip-position="bottom"]` | Positions tooltip below host.                                |
-| `[data-tooltip-position="left"]`   | Positions tooltip left of host.                              |
-| `[data-tooltip-position="right"]`  | Positions tooltip right of host.                             |
-| No `data-tooltip-position`         | Defaults to top placement.                                   |
-| `[data-state="open"]`              | Shows tooltip without hover.                                 |
-
-Example:
-
-```html
-<button
-  class="tooltip tooltip-icon"
-  data-tooltip="More details"
-  data-tooltip-position="right"
-  aria-label="More details"
->
-  ?
-</button>
-```
-
-CSS pseudo-element tooltips are presentational. They are not a complete accessible tooltip implementation by themselves.
-
-## Typography Utilities
-
-All typography classes and `.selection-contrast` are `@utility` classes.
-
-| Class                 | Purpose                                                      |
-| --------------------- | ------------------------------------------------------------ |
-| `.text-display`       | Large display headings.                                      |
-| `.text-title-lg`      | Large section titles.                                        |
-| `.text-title`         | Default section titles.                                      |
-| `.text-title-sm`      | Smaller titles or card titles.                               |
-| `.text-label-lg`      | Large label text.                                            |
-| `.text-label`         | Default label text.                                          |
-| `.text-body`          | Default body copy.                                           |
-| `.selection-contrast` | Inverts `::selection` colors to primary-contrast background. |

package/docs/roadmap.md

@@ -1,34 +0,0 @@
-# Roadmap
-
-**Status:** APPROVED
-**Last updated:** 2026-06-23
-**Scope:** `@codenhub/styles` package direction.
-
-## Purpose
-
-This roadmap tracks durable direction for `@codenhub/styles`. It captures styling-system improvements that should guide future changes without turning this document into a release checklist.
-
-## Recently Completed
-
-- Published the v0.0.2 foundation: design tokens (colors, layout, radius, motion, focus, shadows, layering, dark mode), presentation/helper classes (buttons, forms, feedback, loaders, tooltips), accessibility contrast verification, and multi-path bundler visual regression tests.
-
-## Planned
-
-- **Aesthetic Themes**: Add aesthetic themes (e.g., glassmorphism, brutalism, glitch) to allow changing the whole look-and-feel of the UI.
-- **Layout Helpers**: Expand layout helpers to support common page structure and flex/grid requirements.
-- **Dynamic Tokens & Color Schemes**: Add `@codenhub/theme` as a dev dependency to enable dynamic token changes and color scheme creation.
-- **Button Presentation Classes**: Consider adding more presentation classes for buttons (e.g., loading state enhancements) once component APIs stabilize.
-- **Compatibility Tests**: Add more explicit compatibility tests for intent and presentation combinations when new combinations are supported.
-
-## Not Planned
-
-- **JS/TS Helpers**: Runtime DOM helpers (such as a typed `createElement` wrapper) are not planned for now. They will be considered further before any future package expansion, but remain out of scope for now to keep the package CSS-only.
-- Public JavaScript behavior like toast dismissal, focus management, and app-level theme state remain outside the CSS package.
-
-## References
-
-- [Overview](./index.md)
-- [Tokens](./tokens.md)
-- [Classes](./classes.md)
-- [Accessibility](./accessibility.md)
-- [Tests](./tests.md)

package/docs/tests.md

@@ -1,128 +0,0 @@
-# Styles Test Strategy
-
-**Status:** APPROVED
-**Last updated:** 2026-06-16
-**Scope:** `@codenhub/styles` package test strategy.
-
-## Goal
-
-Validate `@codenhub/styles` before publishing changes across both supported consumer paths:
-
-- Ready-to-import compiled CSS.
-- Tailwind CSS build-time source CSS.
-
-Keep tests package-local and focused on visual confidence plus build compatibility.
-
-## Structure
-
-```text
-packages/styles/
-  tests/
-    preview/
-    vanilla/
-    build/
-    browser/
-  scripts/
-```
-
-## `tests/preview`
-
-Shared manual and automated preview page for both supported consumer paths.
-
-Open with one of these URLs when running the package dev server:
-
-```text
-http://localhost:5173/tests/preview/index.html?env=vanilla
-http://localhost:5173/tests/preview/index.html?env=build
-```
-
-The page loads `tests/vanilla/output.css` for `env=vanilla` and `tests/build/output.css` for `env=build`.
-
-The floating environment toggle switches the `env` query value between `vanilla` and `build`. Its tooltip names the target environment with `See build` or `See vanilla`.
-
-Cover:
-
-- Tokens in light and dark mode.
-- Typography utilities.
-- Buttons: intent, presentation, disabled, and loading states.
-- Layout helpers, surfaces, forms, feedback, tooltips, and sections.
-- Selection and base styles.
-- Tailwind token utilities, dark variants, and responsive variants.
-
-Purpose: keep one HTML fixture while validating both real CSS outputs.
-
-## `tests/vanilla`
-
-Compiled CSS output for vanilla consumers.
-
-Use built package CSS only:
-
-```css
-@import "../../dist/index.css";
-```
-
-Purpose: confirm canonical `@codenhub/styles` output looks right with no Tailwind consumer build.
-
-## `tests/build`
-
-Build validation for Tailwind consumers.
-
-Use source entrypoint:
-
-```css
-@import "tailwindcss";
-@import "@codenhub/styles/tw";
-
-@source "../preview/index.html";
-```
-
-Cover:
-
-- Tailwind can process package source.
-- Token utilities work, such as `bg-background`, `text-text`, `font-default`.
-- Dark variant works with `.dark`.
-- Component classes build correctly.
-- Responsive token variants work.
-
-Purpose: confirm `@codenhub/styles/tw` works in consumer Tailwind builds.
-
-## `tests/browser`
-
-Cross-browser automation for visual and computed-style confidence.
-
-Use Playwright by default.
-
-Tests load the same preview page twice with different `env` query values.
-
-Cover:
-
-- Chromium.
-- Firefox.
-- WebKit.
-- Page load assertions.
-- Key computed style assertions.
-- Optional screenshots for visual review.
-
-Purpose: catch browser-specific CSS regressions before publishing changes.
-
-## Scripts
-
-Default package checks:
-
-```json
-{
-  "test": "pnpm typecheck && pnpm test:build && pnpm test:visual",
-  "test:build": "pnpm build && pnpm test:build:vanilla && pnpm test:build:tw",
-  "test:visual": "playwright test",
-  "dev": "node ./scripts/dev.js"
-}
-```
-
-`pnpm dev` starts a local static server and watches both CSS test builds.
-
-## Priority
-
-1. Keep `tests/preview` as the single shared HTML fixture.
-2. Keep `tests/vanilla` for compiled CSS output.
-3. Keep `tests/build` for Tailwind source build validation.
-4. Keep `tests/browser` for Playwright cross-browser validation.