@codenhub/styles 0.0.3 → 0.1.0

package/docs/index.md

@@ -1,73 +1,62 @@
-# @codenhub/styles Overview
-
-**Status:** IMPLEMENTED
-**Last updated:** 2026-06-18
-**Scope:** `@codenhub/styles` package.
-
-`@codenhub/styles` is a CSS-only styling foundation for Codenhub interfaces. It provides tokens, base styles, typography utilities, layout helpers, component helper classes, and Tailwind CSS v4 source entrypoints.
-
-The package has no JavaScript runtime. It does not create DOM nodes, attach event listeners, manage focus, validate forms, dismiss toasts, or provide framework components.
-
-## Public Entrypoints
-
-| Path                             | Contents                                                              |
-| -------------------------------- | --------------------------------------------------------------------- |
-| `@codenhub/styles`               | Full compiled stylesheet: theme, base styles, components, typography. |
-| `@codenhub/styles/theme`         | Compiled theme tokens and dark-mode variables.                        |
-| `@codenhub/styles/components`    | Compiled theme tokens plus component classes.                         |
-| `@codenhub/styles/tw`            | Tailwind v4 source for theme, base styles, components, and utilities. |
-| `@codenhub/styles/tw/theme`      | Tailwind v4 source for theme tokens and custom dark variant.          |
-| `@codenhub/styles/tw/components` | Tailwind v4 source for theme tokens and component classes.            |
-| `@codenhub/styles/tw/surface`    | Tailwind v4 source for surface styles and empty-state utility.        |
-| `@codenhub/styles/tw/button`     | Tailwind v4 source for composable button utilities.                   |
-| `@codenhub/styles/tw/form`       | Tailwind v4 source for form, inputs, checkbox, and switch utilities.  |
-| `@codenhub/styles/tw/feedback`   | Tailwind v4 source for alert, badge, skeleton, and progress.          |
-| `@codenhub/styles/tw/loader`     | Tailwind v4 source for loader and activity indicator utilities.       |
-| `@codenhub/styles/tw/tooltip`    | Tailwind v4 source for tooltip utility.                               |
-| `@codenhub/styles/tw/utilities`  | Tailwind v4 source for layout primitives and contrast utilities.      |
-
-`components` entrypoints include theme tokens because component classes depend on those variables.
-
-## Class Model
-
-Helper classes are designed as small composable CSS contracts:
-
-- Intent classes define meaning, such as `.primary`, `.success`, `.warning`, `.destructive`, and `.info`.
-- Presentation classes define treatment, such as `.out`, `.ghost`, `.soft`, `.sm`, `.lg`, and `.icon`.
-- State classes or attributes define current state, such as `.loading`, `.disabled`, `[disabled]`, `[aria-disabled="true"]`, `[data-disabled]`, `[aria-invalid="true"]`, and `[data-state="open"]`.
-
-Button example:
-
-```html
-<button class="btn success out">Success outline</button>
-<button class="btn destructive ghost">Danger ghost</button>
-<button class="btn primary loading" disabled>Saving</button>
-```
-
-`out`, `ghost`, and `soft` are presentation choices. They consume active intent tone slots instead of carrying a fixed color intent; for example, `.btn.success.soft` uses success subtle and strong tones.
-
-## Token Model
-
-Component classes use public foundation tokens for shape, motion, focus, surface, and state behavior. Internal scoped variables may exist to compose class variants, but they are not the public customization contract.
-
-Example future-ready profile shape:
-
-```css
-.custom-profile {
-  --radius-surface: 1.25rem;
-  --elevation-low: 0 24px 60px rgb(0 0 0 / 0.18);
-  --motion-duration-normal: 240ms;
-}
-```
-
-Aesthetic profile classes such as `.glassmorphism` or `.brutalism` are not part of v0.0.2. v0.0.2 provides the token foundation that makes them possible later.
-
-## Documentation Map
-
-| Document                            | Purpose                                                   |
-| ----------------------------------- | --------------------------------------------------------- |
-| [Tokens](./tokens.md)               | Theme and foundation variable contracts.                  |
-| [Classes](./classes.md)             | Public helper class behavior and composition rules.       |
-| [Accessibility](./accessibility.md) | CSS accessibility hooks and responsibilities outside CSS. |
-| [Tests](./tests.md)                 | Build and browser validation strategy.                    |
-| [Roadmap](./roadmap.md)             | Draft direction and durable planning context.             |
+---
+title: Introduction
+description: What @codenhub/styles is, what it covers, and where to go next.
+---
+
+# @codenhub/styles
+
+`@codenhub/styles` is a CSS-only design system: tokens, a reset, typography and
+layout utilities, and composable classes for buttons, forms, feedback,
+surfaces, and tooltips. Every component separates three independent choices —
+which color, how much of it, and what it's made of — so changing one never
+requires a component-specific variant. Four optional aesthetics
+(`.neobrutalism`, `.glass`, `.pixel`, `.chunky-tile`) restyle that same
+component set without touching markup.
+
+The package ships as ready-to-import compiled CSS, or as Tailwind CSS v4
+source entrypoints for a project that already runs Tailwind. Both cover the
+same classes; the difference is which build processes them.
+
+## What it does
+
+- Publishes color, foundation, intent, presentation, and material design
+  tokens as CSS custom properties, themed with `light-dark()`.
+- Provides a reset, focus-visible handling, and responsive layout/content
+  utilities.
+- Provides composable classes for buttons, form controls and toggles, alerts,
+  badges, loaders, progress, cards/panels, tables, quotes, code, and
+  tooltips.
+- Provides four opt-in aesthetics that restyle the same components by setting
+  material tokens, not by adding component variants.
+- Provides classless mappings so plain HTML elements pick up base styling
+  without added classes, from a dedicated entrypoint.
+- Publishes Tailwind CSS v4 source entrypoints alongside the compiled output.
+
+## What it does not do
+
+- No JavaScript. There is no runtime, no framework bindings, and no build-time
+  code generation beyond the CSS itself.
+- No semantic HTML, ARIA, keyboard behavior, focus management, validation, or
+  announcement timing. See [Accessibility](./accessibility.md) for the exact
+  line between what the CSS provides and what an application must still add.
+- No theme-toggling logic. Theme selection is a class or attribute a consumer
+  applies; wiring a toggle to system preference, storage, or a user setting is
+  outside this package. The `@codenhub/theme` package covers that need for
+  consumers who want it.
+- No shipped font binaries. `.pixel` and `.chunky-tile` accept a
+  consumer-supplied font and fall back to a system stack when none is given.
+- No compatibility layer for removed tokens or classes. Breaking changes are
+  documented, not silently aliased.
+
+## Next steps
+
+- [Setup](./setup.md): Install the package, choose an entrypoint, and render a
+  first component.
+- [Concepts](./concepts.md): The three-axis model, the token system, and how
+  theme selection works — read this before the usage guides.
+- [Usage](./usage/index.md): Guides for composing axes, theming, customizing,
+  aesthetics, and each component family.
+- [Integrating](./integrating/index.md): Wiring the stylesheet into Next.js,
+  Vue, Svelte, Astro, or a Tailwind CSS v4 build.
+- [Accessibility](./accessibility.md): CSS accessibility hooks and what
+  remains an application responsibility.

package/docs/integrating/astro.md

@@ -0,0 +1,29 @@
+---
+title: Astro
+description: Loading the stylesheet in an Astro app.
+---
+
+# Astro
+
+Import the package from a shared layout's frontmatter so every page that
+uses that layout loads it once:
+
+```astro
+---
+// src/layouts/Layout.astro
+import "@codenhub/styles";
+---
+
+<html lang="en">
+  <body>
+    <slot />
+  </body>
+</html>
+```
+
+Apply `.dark` or `.light` on `<html>` to force a theme instead of following
+the system preference; see [Setup → Configuration](../setup.md#configuration).
+
+A project running Tailwind CSS v4 imports `@codenhub/styles/tw` through
+Astro's Tailwind integration instead; see [Tailwind CSS v4](./tailwind.md)
+for the `@source` directive Astro needs to scan `src/`.

package/docs/integrating/index.md

@@ -0,0 +1,32 @@
+---
+title: Integrating
+description: Wiring the stylesheet into a framework or build target.
+---
+
+# Integrating
+
+This package has no JavaScript and no framework bindings; see
+[Introduction](../index.md#what-it-does-not-do). Integrating it into a
+framework is entirely about where that framework loads a global stylesheet,
+and whether the project runs Tailwind CSS v4.
+
+Every stack does the same two things:
+
+1. Import one [entrypoint](../setup.md#import-paths) — the compiled
+   `@codenhub/styles` for any build, or `@codenhub/styles/tw` when the
+   project already runs Tailwind CSS v4 — from wherever that framework loads
+   global CSS.
+2. Import `@codenhub/styles/aesthetics` (or `/tw/aesthetics`) after it, only
+   if the project uses an [aesthetic](../usage/aesthetics.md).
+
+| Stack                                    | Guide                            |
+| ---------------------------------------- | -------------------------------- |
+| A Tailwind CSS v4 project on any bundler | [Tailwind CSS v4](./tailwind.md) |
+| Next.js / React                          | [Next.js](./nextjs.md)           |
+| Vue                                      | [Vue](./vue.md)                  |
+| Svelte / SvelteKit                       | [Svelte](./svelte.md)            |
+| Astro                                    | [Astro](./astro.md)              |
+
+A project with no framework — a plain Vite, webpack, or Parcel build — needs
+nothing beyond [Setup](../setup.md#quick-start): import the compiled
+stylesheet from the project's existing global CSS entry.

package/docs/integrating/nextjs.md

@@ -0,0 +1,44 @@
+---
+title: Next.js
+description: Loading the stylesheet in a Next.js / React app.
+---
+
+# Next.js
+
+Next.js only allows global CSS to be imported from one place. Import the
+package from the root layout in the App Router, or from the custom App in
+the Pages Router — not from a page or component further down the tree.
+
+```tsx
+// app/layout.tsx
+import "@codenhub/styles";
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en">
+      <body>{children}</body>
+    </html>
+  );
+}
+```
+
+```tsx
+// pages/_app.tsx
+import "@codenhub/styles";
+import type { AppProps } from "next/app";
+
+export default function App({ Component, pageProps }: AppProps) {
+  return <Component {...pageProps} />;
+}
+```
+
+Apply `.dark` or `.light` on `<html>` to force a theme instead of following
+the system preference; see [Setup → Configuration](../setup.md#configuration).
+
+```tsx
+<html lang="en" className="dark">
+```
+
+A project running Tailwind CSS v4 imports `@codenhub/styles/tw` from the
+same file instead; see [Tailwind CSS v4](./tailwind.md) for the `@source`
+directive Next.js needs to scan its own `app`/`src` directories.

package/docs/integrating/svelte.md

@@ -0,0 +1,37 @@
+---
+title: Svelte
+description: Loading the stylesheet in a Svelte / SvelteKit app.
+---
+
+# Svelte
+
+In SvelteKit, import the package from the root layout so it loads once for
+every route:
+
+```svelte
+<!-- src/routes/+layout.svelte -->
+<script>
+  import "@codenhub/styles";
+  let { children } = $props();
+</script>
+
+{@render children()}
+```
+
+In a plain Svelte + Vite app, import it from the entry file instead:
+
+```ts
+// main.ts
+import "@codenhub/styles";
+import { mount } from "svelte";
+import App from "./App.svelte";
+
+mount(App, { target: document.getElementById("app")! });
+```
+
+Apply `.dark` or `.light` on `<html>` (edit `src/app.html` in SvelteKit) to
+force a theme instead of following the system preference; see
+[Setup → Configuration](../setup.md#configuration).
+
+A project running Tailwind CSS v4 imports `@codenhub/styles/tw` from the
+app's CSS entry instead; see [Tailwind CSS v4](./tailwind.md).

package/docs/integrating/tailwind.md

@@ -0,0 +1,40 @@
+---
+title: Tailwind CSS v4
+description: Using the /tw source entrypoints in a Tailwind CSS v4 project.
+---
+
+# Tailwind CSS v4
+
+A project that already runs Tailwind CSS v4 can process this package's
+source instead of its compiled output. `/tw` entrypoints publish copied,
+uncompiled source from `dist/tw`; your own Tailwind build compiles it
+alongside your app, so its `@theme`, `@utility`, and `@apply` directives
+resolve together with yours.
+
+```css
+@import "tailwindcss";
+@import "@codenhub/styles/tw";
+
+@source "./src";
+```
+
+`@source` tells Tailwind's build where to scan for the utility and component
+class names actually used in your markup, so it can generate only what is
+referenced. Point it at your app's source, not at this package — `/tw`
+already ships every class definition it publishes.
+
+Add aesthetics from the source entrypoint the same way as the compiled one,
+after the base import:
+
+```css
+@import "tailwindcss";
+@import "@codenhub/styles/tw";
+@import "@codenhub/styles/tw/aesthetics";
+
+@source "./src";
+```
+
+Import a focused `/tw/*` entrypoint instead of the combined one — such as
+`/tw/button` or `/tw/form` — when a build only needs one component family;
+see the full [import path table](../setup.md#import-paths) for what each one
+composes. Tailwind CSS 4 or newer is required for every `/tw` entrypoint.

package/docs/integrating/vue.md

@@ -0,0 +1,25 @@
+---
+title: Vue
+description: Loading the stylesheet in a Vue / Vite app.
+---
+
+# Vue
+
+Import the package once, from the app's entry file, before the app mounts:
+
+```ts
+// main.ts
+import "@codenhub/styles";
+import { createApp } from "vue";
+import App from "./App.vue";
+
+createApp(App).mount("#app");
+```
+
+Apply `.dark` or `.light` on the root element to force a theme instead of
+following the system preference; see
+[Setup → Configuration](../setup.md#configuration).
+
+A project running Tailwind CSS v4 imports `@codenhub/styles/tw` from a CSS
+entry file instead of `main.ts`, using the `@tailwindcss/vite` plugin; see
+[Tailwind CSS v4](./tailwind.md).

package/docs/setup.md

@@ -0,0 +1,116 @@
+---
+title: Setup
+description: Install the package, pick an entrypoint, and render a first component.
+---
+
+# Setup
+
+## Installation
+
+```sh
+pnpm add @codenhub/styles
+```
+
+## Quick start
+
+Import the compiled stylesheet for the complete token, reset, utility, and
+component-class surface, then compose helper classes in markup:
+
+```css
+@import "@codenhub/styles";
+```
+
+```html
+<main class="stack">
+  <p class="text-label">Status</p>
+  <h1 class="text-title">Ready to publish</h1>
+  <button class="btn primary">Continue</button>
+</main>
+```
+
+The full stylesheet applies global reset and focus-visible rules, but does not
+apply the optional classless native-element mappings, and does not include
+aesthetics. Import focused entrypoints when global rules are not appropriate;
+see [Import paths](#import-paths) below.
+
+Aesthetics are opt-in. Import the combined aesthetics stylesheet, or one
+aesthetic on its own, after the base stylesheet so its rules win:
+
+```css
+@import "@codenhub/styles";
+@import "@codenhub/styles/aesthetics";
+```
+
+```html
+<section class="neobrutalism">
+  <button class="btn primary">Thick ink and a hard shadow</button>
+</section>
+```
+
+A project already running Tailwind CSS v4 imports the source entrypoint
+instead; see [Integrating → Tailwind CSS v4](./integrating/tailwind.md).
+
+## Configuration
+
+The root follows the operating-system color-scheme preference. Apply `.light`
+or `.dark` to the root or any ancestor to force token values for that subtree.
+`.theme-light`, `.theme-dark`, and `data-theme="light|dark"` are aliases.
+
+```html
+<html class="dark">
+  <body>
+    <button class="btn primary">Dark themed button</button>
+  </body>
+</html>
+```
+
+See [Concepts → Theme selection](./concepts.md#theme-selection) for how
+selectors resolve and [Usage → Theming](./usage/theming.md) for the full color
+token reference.
+
+## Import paths
+
+Compiled entrypoints are ready-to-import CSS and require only tooling that can
+resolve package CSS imports. `/tw` entrypoints publish copied, uncompiled
+source from `dist/tw`; a Tailwind v4 build must still process their `@theme`,
+`@utility`, `@apply`, and related directives. Focused source component
+entrypoints include theme tokens so their classes can work independently.
+
+| Import path                      | Composition and effects                                                                                                                                                                                           |
+| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `@codenhub/styles`               | Compiled complete surface: Tailwind base/theme output, tokens, typography, utilities, components, and reset. Applies global reset, root theme, and focus rules.                                                   |
+| `@codenhub/styles/theme`         | Compiled Tailwind theme variables, Codenhub tokens, and the presentation classes. Sets root theme properties and system/explicit theme selectors; no reset or component classes.                                  |
+| `@codenhub/styles/components`    | Compiled theme tokens, typography utilities, and every component class. Includes static reduced-motion loader masks; no reset, layout/content utilities, or native mappings.                                      |
+| `@codenhub/styles/native`        | Compiled complete surface plus classless mappings for headings, text, content elements, form controls, and buttons. Applies the reset and broad element selectors.                                                |
+| `@codenhub/styles/aesthetics`    | Compiled `.neobrutalism`, `.glass`, `.pixel`, and `.chunky-tile` classes. Adds no tokens or components of its own; import after the base stylesheet.                                                              |
+| `@codenhub/styles/aesthetics/*`  | One compiled aesthetic: `/neobrutalism`, `/glass`, `/pixel`, or `/chunky-tile`. Same rules and ordering as the combined file.                                                                                     |
+| `@codenhub/styles/tw`            | Source equivalent of the complete stylesheet. Imports Tailwind itself, theme, typography, utilities, components, and reset; applies the same global rules.                                                        |
+| `@codenhub/styles/tw/theme`      | Source theme, tokens, and presentation classes. Imports Tailwind's theme layer; emits root/system/explicit theme selectors and defines the package's custom `dark:` variant.                                      |
+| `@codenhub/styles/tw/components` | Published Tailwind source for theme, typography, buttons, feedback, forms, loaders, surfaces, and tooltips, including static reduced-motion loader masks. No reset, layout/content utilities, or native mappings. |
+| `@codenhub/styles/tw/surface`    | Source theme plus `.surface`, `.card`, and `.panel`.                                                                                                                                                              |
+| `@codenhub/styles/tw/button`     | Published Tailwind source for theme, activity indicators, and `.btn`; includes static reduced-motion masks because buttons compose `.loader-mask` for loading state.                                              |
+| `@codenhub/styles/tw/form`       | Source theme plus field, public `text-control`, input, textarea, select, checkbox, radio, and switch utilities.                                                                                                   |
+| `@codenhub/styles/tw/feedback`   | Source theme plus alert, badge, skeleton, and progress utilities and their keyframes.                                                                                                                             |
+| `@codenhub/styles/tw/loader`     | Published Tailwind source for activity indicators and loaders, including static reduced-motion masks. It has no theme or reset side effects and uses `currentColor`.                                              |
+| `@codenhub/styles/tw/tooltip`    | Source theme plus tooltip utilities.                                                                                                                                                                              |
+| `@codenhub/styles/tw/reset`      | Source theme, typography utilities, and global reset/accessibility rules. It changes root/body/elements and selection, motion, focus, scrollbar, and forced colors.                                               |
+| `@codenhub/styles/tw/native`     | Source complete surface plus reset and classless native-element mappings; broadest global effects.                                                                                                                |
+| `@codenhub/styles/tw/typography` | Source theme plus typography utilities; sets theme selectors but no reset or classless mappings.                                                                                                                  |
+| `@codenhub/styles/tw/utilities`  | Source theme and typography composition plus layout and content utilities; safelists the package utility names.                                                                                                   |
+| `@codenhub/styles/tw/aesthetics` | Source aesthetics, combined. `/tw/aesthetics/neobrutalism`, `/glass`, `/pixel`, and `/chunky-tile` publish one apiece. Plain CSS with no theme or reset side effects.                                             |
+
+Avoid importing overlapping entrypoints in the same build unless duplicate
+generated CSS is acceptable; pick the narrowest entrypoint that covers what a
+page needs.
+
+## Requirements
+
+- Consumer tooling must resolve package CSS imports.
+- Chrome 123, Safari 17.5, or Firefox 121 and newer. Color tokens are declared
+  with `light-dark()` and selected by `color-scheme` (Firefox 120), and
+  `.input-group` propagates a nested control's invalid and disabled state with
+  `:has()` (Firefox 121).
+- Tailwind CSS 4 or newer is required only for `/tw` source entrypoints.
+- The package has no JavaScript runtime. Apps must provide semantic HTML,
+  ARIA, keyboard behavior, focus management, validation, and announcements;
+  see [Accessibility](./accessibility.md).