@codenhub/styles 0.0.3 → 0.1.0

package/docs/usage/forms.md

@@ -0,0 +1,177 @@
+---
+title: Forms
+description: Field, text control, and toggle class reference.
+---
+
+# Forms
+
+| Class or Selector                                                     | Purpose                                                       |
+| --------------------------------------------------------------------- | ------------------------------------------------------------- |
+| `.field`                                                              | Vertical field wrapper.                                       |
+| `.label`                                                              | Form label text.                                              |
+| `.hint`                                                               | Secondary helper text.                                        |
+| `.hint.error`                                                         | Helper text with destructive intent.                          |
+| `.surface`                                                            | Shared public container composition utility.                  |
+| `.text-control`                                                       | Shared public text-control composition utility.               |
+| `.ipt`                                                                | Input control styling.                                        |
+| `.input-group`                                                        | Wrapper that owns the field box so a control can carry icons. |
+| `.textarea`                                                           | Textarea control styling.                                     |
+| `.select`                                                             | Select control styling.                                       |
+| `input[type="checkbox"].checkbox`                                     | Custom checkbox control styling.                              |
+| `input[type="radio"].radio`                                           | Custom radio 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.                                             |
+
+## Icons
+
+The package ships no icons. It used to paint one per input type as a
+`background-image` — a `data:` URI, which cannot read `currentColor` or a
+custom property, so every glyph shipped a light and a dark copy and a theme
+selector chose between them. That put icon artwork, and the package's only
+theme-by-selector branch, inside a CSS-only design system whose glyphs did
+not fit every aesthetic. Icons are the consumer's to choose now.
+
+`.input-group` is the wrapper for a control that carries one. It owns the
+field box — border, radius, fill, focus ring, invalid and disabled state —
+and the control inside it goes flush, so the boundary is drawn once. Any
+icon element works, placed before the control for a leading icon or after it
+for a trailing one: an inline `<svg>`, an `<img>`, or a class from an icon
+set such as `@codenhub/icons`.
+
+```html
+<label class="field">
+  <span class="label">Email</span>
+  <div class="input-group">
+    <svg viewBox="0 0 24 24" width="16" height="16" fill="none" stroke="currentColor" aria-hidden="true">
+      <rect width="20" height="16" x="2" y="4" rx="2" />
+      <path d="m22 7-8.991 5.727a2 2 0 0 1-2.009 0L2 7" />
+    </svg>
+    <input class="ipt" type="email" />
+  </div>
+</label>
+<label class="field">
+  <span class="label">Search</span>
+  <div class="input-group">
+    <input class="ipt" type="search" />
+    <i class="ic-search" aria-hidden="true"></i>
+  </div>
+</label>
+```
+
+The group reads intent and both [presentation](./composing.md#presentation)
+axes the same way a lone `.ipt` does — `.input-group.soft.edgeless` is the
+sunk variant, `.input-group.primary` colors the boundary — and follows
+whichever [aesthetic](./aesthetics.md) is in scope. `aria-invalid` or
+`disabled` on the control inside propagates to the group; so does either on
+the group itself. Focus is shown with `:focus-within`, so unlike a lone
+field the ring also appears on a mouse click.
+
+Non-icon input types keep the browser's native `date` and `datetime-local`
+pickers. WebKit's native `search` decorations are still suppressed on
+`.text-control` to keep them from overlapping the value.
+
+## Toggles
+
+`.checkbox`, `.radio`, and `.switch` accept the same intent classes as
+buttons to set the checked color:
+
+| Class                               | Meaning                 |
+| ----------------------------------- | ----------------------- |
+| `.neutral` _(default)_              | Text color, capped.     |
+| `.primary`                          | Primary color.          |
+| `.secondary`                        | Secondary/accent color. |
+| `.success`                          | Success color.          |
+| `.warning`                          | Warning color.          |
+| `.destructive`, `.danger`, `.error` | Destructive color.      |
+| `.info`                             | Info color.             |
+
+All three toggles rest at `.solid`, and **`.ghost` is not supported on any of
+them.** An unchecked ghost toggle is the silhouette every toggle already
+has, and a checked one is a mark on nothing — a tick floating on the page, a
+dot with no ring around it. A container that cascades `.ghost` onto a
+toggle is floored rather than obeyed.
+
+Presentation decides the fill in both states. Being checked lifts the cap
+rather than pinning a fill, so the class still chooses:
+
+| Toggle            | unchecked       | checked                         |
+| ----------------- | --------------- | ------------------------------- |
+| `.solid`, default | 20%, switch 40% | 100%, mark in the contrast tone |
+| `.soft`           | 12%             | 12%, mark in the strong tone    |
+
+A checked checkbox and a checked switch cut their mark out of that plate. A
+checked radio thickens its ring to twice the resting line and takes the
+intent whole on it, so `.radio.soft` is the classic ring-and-dot radio and
+`.radio.solid` is a filled circle whose dot stays readable — the mark
+follows the plate rather than being pinned to the intent color.
+
+## Text controls
+
+Text controls also take intent, which colors the resting border and the
+focus-visible border, and both [presentation](./composing.md#presentation)
+axes. `.ghost` fills nothing, `.soft` takes `12%`, and `.solid` takes `20%`
+— quiet enough that typed text still reads on it, and ordered so the louder
+name draws the stronger tint. None of them touches the line.
+
+The boundary is the edge axis's, and it splits the same way. A container's
+`.edgeless` is floored, so a toolbar cannot leave a field with no mark of
+where typing goes. `.edgeless` on the control itself is honoured, which is
+how the borderless field is spelled — it does not meet WCAG 1.4.11 at rest,
+so it is opt-in and never a default, and the focus ring still shows.
+
+```html
+<input class="ipt success" placeholder="Valid" />
+<input class="ipt ghost edged" placeholder="Outlined" />
+<input class="ipt soft edged" placeholder="Tinted with a border" />
+<input class="ipt soft edgeless" placeholder="Sunk into the page" />
+<div class="soft">
+  <input class="ipt" placeholder="Tinted from the container, capped at 6%" />
+</div>
+<div class="edgeless">
+  <input class="ipt" placeholder="Keeps its line; the floor holds" />
+</div>
+```
+
+`.surface` is a public low-level utility. It is the box every container in
+the package composes: ghost, edged, surface radius, and the two slots only
+a surface resolves — the backdrop filter and the complete surface shadow.
+Use it to paint a container the package does not ship, under whichever
+aesthetic is in scope. Prefer `.card` or `.panel` when they fit.
+
+```html
+<div class="surface glass">Blurred, translucent, glass corners</div>
+<div class="surface pixel">Cut corners and an inset ring</div>
+<div class="surface primary solid">Any intent, any presentation</div>
+```
+
+`.text-control` is a public low-level utility from the form entrypoint. It
+provides the shared control dimensions, border, placeholder, focus-visible,
+invalid, and disabled styles composed by `ipt`, `textarea`, and `select`.
+Use it for custom text-like controls; prefer those higher-level utilities
+when they fit.
+
+## Example
+
+```html
+<label class="field">
+  <span class="label">Email</span>
+  <input class="ipt" type="email" aria-invalid="true" aria-describedby="email-error" />
+  <span class="hint 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="radio" class="radio secondary" name="plan" />
+  <span>Standard plan</span>
+</label>
+<label style="display: flex; gap: 0.5rem; align-items: center">
+  <input type="checkbox" class="switch destructive" />
+  <span>Enable</span>
+</label>
+```
+
+Use labels, `type`, validation logic, `aria-describedby`, and error message
+relationships; see [Accessibility](../accessibility.md).

package/docs/usage/index.md

@@ -0,0 +1,32 @@
+---
+title: Usage
+description: Guides for composing axes, theming, customizing, aesthetics, and each component family.
+---
+
+# Usage
+
+These guides assume the [Concepts](../concepts.md) mental model: intent,
+presentation, and aesthetic as three independent axes, resolved through
+tokens a component reads.
+
+- [Composing](./composing.md): Combining the three axes on a component, the
+  axis-support matrix, and elevation modifiers.
+- [Theming](./theming.md): The color, intent, and foundation token reference.
+- [Customizing](./customizing.md): The presentation and material token
+  reference, aesthetic knobs, and defining a custom intent.
+- [Aesthetics](./aesthetics.md): Each shipped aesthetic in depth, including
+  its documented exceptions.
+- [Buttons](./buttons.md)
+- [Forms](./forms.md)
+- [Feedback](./feedback.md)
+- [Tooltips](./tooltips.md)
+- [Content and layout](./content-and-layout.md): Layout helpers, tables,
+  quotes, code, surfaces, and typography utilities.
+
+## Supported surface
+
+A class, component, and axis combination is supported when this documentation
+describes it and the package playground demonstrates it. Undocumented and
+undemonstrated combinations may still produce CSS, but are not maintained
+behavior. Playground variant matrices are the exhaustive demonstrations; small
+examples elsewhere illustrate usage without widening that contract.

package/docs/usage/theming.md

@@ -0,0 +1,210 @@
+---
+title: Theming
+description: The color, intent, and foundation token reference.
+---
+
+# Theming
+
+Color tokens are how you restyle the palette; see
+[Concepts → Theme selection](../concepts.md#theme-selection) for how a theme
+is chosen. Intent tokens are how a component reads that palette once an
+intent class is applied. Foundation tokens are the shared layout, shape, and
+motion defaults underneath everything.
+
+## Color tokens
+
+Each color token holds both of its theme values at once through
+`light-dark()`, and the element's `color-scheme` picks one.
+
+```html
+<section data-theme="dark">
+  <article>Dark token subtree</article>
+</section>
+```
+
+| Token                          | Purpose                                                                                                           |
+| ------------------------------ | ----------------------------------------------------------------------------------------------------------------- |
+| `--color-primary`              | Primary action/content color.                                                                                     |
+| `--color-primary-contrast`     | Text/icon color on primary filled surface.                                                                        |
+| `--color-primary-hover`        | Primary hover state.                                                                                              |
+| `--color-primary-subtle`       | Low-emphasis companion tone for primary. Use as soft surface or subtle background.                                |
+| `--color-primary-strong`       | High-emphasis companion tone for primary. Use as readable text, icon, or border on subtle surfaces.               |
+| `--color-accent`               | Secondary/accent surface.                                                                                         |
+| `--color-accent-contrast`      | Text/icon color on accent filled surface.                                                                         |
+| `--color-accent-hover`         | Accent hover state.                                                                                               |
+| `--color-accent-subtle`        | Low-emphasis companion tone for accent. Use as soft surface or subtle background.                                 |
+| `--color-accent-strong`        | High-emphasis companion tone for accent. Use as readable text, icon, or border on subtle surfaces.                |
+| `--color-border`               | Default border color.                                                                                             |
+| `--color-border-hover`         | Interactive border color.                                                                                         |
+| `--color-control-border`       | Resting line on the six text controls; one value, drawn at a fraction on text inputs.                             |
+| `--color-background`           | Page and default raised surface background.                                                                       |
+| `--color-foreground`           | Subtle raised foreground surface.                                                                                 |
+| `--color-surface`              | Nested or muted surface.                                                                                          |
+| `--color-text`                 | Primary text color.                                                                                               |
+| `--color-text-secondary`       | Secondary text color.                                                                                             |
+| `--color-text-contrast`        | Readable color on top of a full fill of `--color-text`. A checked toggle prints it.                               |
+| `--color-text-hover`           | Text hover state.                                                                                                 |
+| `--color-text-subtle`          | Low-emphasis companion tone for text. Use as soft surface or subtle background.                                   |
+| `--color-text-strong`          | High-emphasis companion tone for text. Use as readable text, icon, or border on subtle surfaces.                  |
+| `--color-tooltip`              | Tooltip bubble plate with no intent. Chosen per theme rather than derived: near-white in light, mid grey in dark. |
+| `--color-tooltip-contrast`     | Ink on `--color-tooltip`.                                                                                         |
+| `--color-success`              | Success state color.                                                                                              |
+| `--color-success-contrast`     | Text/icon color on success filled surface. Meets 4.5:1 as normal text on `--color-success` (5.14:1).              |
+| `--color-success-hover`        | Success hover tone.                                                                                               |
+| `--color-success-subtle`       | Low-emphasis companion tone for success.                                                                          |
+| `--color-success-strong`       | High-emphasis companion tone for success.                                                                         |
+| `--color-warning`              | Warning state color.                                                                                              |
+| `--color-warning-contrast`     | The near-black tone, not the page tone. Meets 4.5:1 as normal text on `--color-warning` (6.19:1).                 |
+| `--color-warning-hover`        | Warning hover tone.                                                                                               |
+| `--color-warning-subtle`       | Low-emphasis companion tone for warning.                                                                          |
+| `--color-warning-strong`       | High-emphasis companion tone for warning.                                                                         |
+| `--color-destructive`          | Destructive/error state color.                                                                                    |
+| `--color-destructive-contrast` | Text/icon color on destructive filled surface. Meets 4.5:1 as normal text on `--color-destructive` (5.78:1).      |
+| `--color-destructive-hover`    | Destructive hover tone.                                                                                           |
+| `--color-destructive-subtle`   | Low-emphasis companion tone for destructive.                                                                      |
+| `--color-destructive-strong`   | High-emphasis companion tone for destructive.                                                                     |
+| `--color-info`                 | Informational state color.                                                                                        |
+| `--color-info-contrast`        | Text/icon color on info filled surface. Meets 4.5:1 as normal text on `--color-info` (6.19:1).                    |
+| `--color-info-hover`           | Info hover tone.                                                                                                  |
+| `--color-info-subtle`          | Low-emphasis companion tone for info.                                                                             |
+| `--color-info-strong`          | High-emphasis companion tone for info.                                                                            |
+
+> **Intent token contract**: color intent tokens own meaning and tone
+> variants. Intent classes map one family onto the shared intent slots below,
+> and presentation classes decide how much of it a component shows. Theme
+> changes belong in token values, not broad component-level theme checks.
+> Component-level theme handling should exist only when a component has an
+> internal structure that cannot be expressed through the token palette
+> alone.
+
+## Intent tokens
+
+Intent classes set these seven slots; components read them. Because every
+supporting component reads the same seven names, an intent works on every
+component that supports intent, and a custom intent needs no component
+changes.
+
+| Token               | Purpose                                                                               |
+| ------------------- | ------------------------------------------------------------------------------------- |
+| `--intent-color`    | The intent's base color. What a fill is made of.                                      |
+| `--intent-contrast` | Readable color on top of a filled `--intent-color`.                                   |
+| `--intent-hover`    | The intent's hovered base color.                                                      |
+| `--intent-strong`   | The intent printed on a page. Text, icon, or border wherever the fill is not full.    |
+| `--intent-subtle`   | Low-emphasis tone. Tinted surfaces and tracks. Neutral resolves to `--color-surface`. |
+| `--intent-border`   | Line color. Resolves to `--color-border` when no intent is set.                       |
+| `--intent-fill-max` | How far a fill of this intent is allowed to go. `100%` for every intent but neutral.  |
+
+`--intent-color` and `--intent-strong` are two ends of the same family and not
+interchangeable. The base is a ground, chosen to be filled with; the strong
+tone is chosen to be read against a page. A `.soft` or `.ghost` component
+prints the strong one, which is why an unfilled warning reads in amber-800
+rather than the amber-600 its solid sibling is filled with.
+
+The strong tone has to stay recognisably its own hue, not just readable. On a
+dark page the `-100` shade of every family is a pale tint that carries almost
+no chroma at small sizes: a soft success badge and a soft destructive one
+printed labels that both read white, and a soft radio's dot stopped matching
+the ring around it. The dark tones are `-300` for that reason, and the tinted
+grounds under them are `-900` so there is room — measured at 5.0:1 or better
+everywhere a partial fill prints text, and past 9:1 on the page.
+
+`--intent-border` exists because a neutral border must stay the quiet border
+gray rather than the text color. Everything that draws a line reads it:
+control borders, table rules, dividers, key caps, and quote bars.
+
+`--intent-fill-max` exists for the neutral intent, whose color is the page's
+own ink. Every other intent is a hue, legible pale at 12% and saturated at
+100%; a grey filled to 100% is a black or white slab, which is the loudest
+thing on the page and the wrong look for the intent that means _nothing in
+particular_. Neutral stops at `20%`, so `.solid` gives it a quiet plate that
+still reads as a step past `.soft`. Hover adds its step on top of the cap, so
+a capped fill still deepens under the pointer.
+
+The foreground is gated by the plate rather than tied to the fill.
+`--intent-contrast` is the ink for a _full_ fill, so printing it at full
+strength on a fifth of one puts white on light grey. Contrast ink therefore
+appears only once the fill is past halfway and reaches full at a full fill;
+below that a component prints `--intent-strong`, the tone chosen to be read.
+
+That means a capped neutral takes the strong tone whole rather than a
+fraction of the way toward the page. Tying it to the fill instead cost a
+neutral `.solid` button four points of contrast and a neutral tooltip nearly
+ten. A state that lifts the cap on purpose — a checked checkbox is filled
+with its own intent by definition — reaches a full fill and gets the contrast
+whole.
+
+Set them directly to define an intent this package does not ship. **State
+every slot**, including `--intent-fill-max`: components reset all seven to
+the neutral values, so a slot your intent leaves out keeps neutral's — and an
+intent that omits the cap fills to 20% of its color instead of 100%.
+
+```css
+.brand {
+  --intent-color: var(--color-violet-600);
+  --intent-contrast: var(--color-neutral-50);
+  --intent-hover: var(--color-violet-700);
+  --intent-strong: var(--color-violet-800);
+  --intent-subtle: var(--color-violet-100);
+  --intent-border: var(--color-violet-600);
+  --intent-fill-max: 100%;
+}
+```
+
+```html
+<button class="btn brand">Custom intent</button>
+<span class="badge brand soft">Works everywhere</span>
+```
+
+> **Intent does not cascade.** Components reset these slots to the text
+> palette at their own root, so a `.success` container never recolors a
+> nested destructive button. Put the intent class on the element that shows
+> the intent.
+
+## Foundation tokens
+
+Foundation tokens are not aliases for one color. They define layout, shape,
+motion, focus, depth, and layering behavior used by helper classes.
+
+The four `--elevation-*` values below are raw shadows for elements you style
+yourself. They are a separate thing from `.elevation-none`/`.elevation-sm`/
+`.elevation-md` (aliased as `.flat`/`.raised`/`.floating`), which scale a
+_component's own_ shadow geometry and default to no shadow at all until an
+aesthetic or one of those classes asks for depth — see
+[Composing → Elevation](./composing.md#elevation) for that system. The two
+share `none`/`sm`/`md`/`lg` naming for the same weight of depth, but one is a
+fixed value and the other multiplies shadow parts, so they will not always
+paint identically.
+
+| Token                      | Purpose                                                                 |
+| -------------------------- | ----------------------------------------------------------------------- |
+| `--font-default`           | Default app font family.                                                |
+| `--container-narrow`       | Narrow content width.                                                   |
+| `--container-max`          | Default content width.                                                  |
+| `--container-wide`         | Wide content width.                                                     |
+| `--layout-gutter`          | Responsive inline page padding.                                         |
+| `--layout-section-block`   | Responsive section vertical padding.                                    |
+| `--layout-gap`             | Shared gap for `.view`, `.stack`, `.cluster`, and `.auto-grid`.         |
+| `--layout-grid-min`        | Minimum column width for `.auto-grid`.                                  |
+| `--radius-small`           | Small radius for compact utility surfaces such as code elements.        |
+| `--radius-control`         | Radius for buttons, inputs, tooltips, and compact UI.                   |
+| `--radius-surface`         | Radius for cards, panels, and alerts.                                   |
+| `--control-height`         | Default minimum height for controls.                                    |
+| `--border-width`           | Default border width.                                                   |
+| `--elevation-color`        | Shadow color the four elevations compose from. Heavier in dark themes.  |
+| `--elevation-none`         | No shadow. Use on an element that should read as flat against its page. |
+| `--elevation-sm`           | A light shadow for your own surface-level elements, such as cards.      |
+| `--elevation-md`           | A shadow for your own raised elements, such as dropdowns and popovers.  |
+| `--elevation-lg`           | A shadow for your own full overlays, such as modal dialogs.             |
+| `--focus-ring`             | Focus-visible ring color.                                               |
+| `--focus-ring-offset`      | Focus-visible outline offset. Negative, so the ring lands on the edge.  |
+| `--focus-ring-width`       | Focus-visible outline/ring width.                                       |
+| `--motion-duration-fast`   | Fast transition for buttons and input interactions (`120ms`).           |
+| `--motion-duration-normal` | Normal transition for layout and modals (`200ms`).                      |
+| `--motion-duration-slow`   | Slow animation for skeleton loaders and progress bars (`400ms`).        |
+| `--motion-ease`            | Default easing curve.                                                   |
+| `--z-popover`              | Popover/tooltip z-index.                                                |
+| `--breakpoint-xs`          | Extra-small Tailwind responsive breakpoint.                             |
+| `--breakpoint-2xl`         | Extended large Tailwind responsive breakpoint.                          |
+
+Next: [Customizing](./customizing.md) covers presentation and material
+tokens — how much of an intent shows, and what a component is made of.

package/docs/usage/tooltips.md

@@ -0,0 +1,45 @@
+---
+title: Tooltips
+description: Tooltip host classes and positioning attributes.
+---
+
+# 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.                                   |
+| `.tooltip.raised` / `.tooltip.floating` | Adds one or two units of depth. The bubble is flat by default. |
+
+A tooltip bubble's fill, ground color, and floor behavior are covered in
+[Composing → Presentation](./composing.md#presentation), and its material
+follows whichever [aesthetic](./aesthetics.md) is in scope, including the
+pseudo-element itself.
+
+The bubble rests flat. It draws no shadow of its own on a plain page, and
+zeroes an aesthetic's part-based depth (such as `.neobrutalism`'s slab) the
+same way `.flat` does elsewhere. Add [`.raised` or
+`.floating`](./composing.md#elevation) to lift it — `.tooltip.floating` is the
+pre-0.1.0 look. An aesthetic whose shadow is a complete value, like `.glass`,
+still reaches the bubble as it reaches any surface.
+
+```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 — provide accessible
+names/descriptions outside the CSS; see [Accessibility](../accessibility.md).