@claralight-design/react 0.0.1

package/styles/anchored.css

@@ -0,0 +1,115 @@
+/**
+ * ClaraLight Design — the anchored overlay surface.
+ *
+ * Popover and Tooltip only. Split out of `base.css` because it is the one part
+ * of the language a project can decline: a build with neither component has no
+ * use for the tail padding, the probe or the grow-from-the-tail entrance.
+ *
+ * Tokens live in `theme.css`; the tail itself is constructed in
+ * `src/lib/anchored.tsx`, which is the other half of this file.
+ *
+ *   @import "tailwindcss";
+ *   @import "@claralight-design/react/styles.css";
+ */
+
+@layer components {
+  /**
+   * Popovers and tooltips.
+   *
+   * The pointing arrow is *not* a second element. It is spliced into the
+   * surface's own smooth-corner path, so fill, backdrop blur and the 1px
+   * outline cross the join as one shape — see `src/lib/anchored.tsx`. A
+   * separate arrow element cannot do that here: ClaraLight's frost fill is
+   * translucent, so an overlap would composite into a visible dark seam and
+   * the body's outline would run straight through the arrow's mouth.
+   *
+   * The consequence for CSS is this padding. The tail lives *inside* the
+   * element's box, occupying `--cl-arrow-extent` on whichever side faces the
+   * anchor, so content has to be inset by that much again or it would sit in
+   * the tail. `[data-side]` is Base UI's, and names the side of the *anchor*
+   * the surface was placed on — so the tail is on the opposite edge.
+   */
+  .cl-anchored {
+    padding: var(--cl-anchored-padding-y) var(--cl-anchored-padding-x);
+  }
+
+  .cl-anchored-arrow[data-side="top"] {
+    padding-bottom: calc(var(--cl-anchored-padding-y) + var(--cl-arrow-extent));
+  }
+
+  .cl-anchored-arrow[data-side="bottom"] {
+    padding-top: calc(var(--cl-anchored-padding-y) + var(--cl-arrow-extent));
+  }
+
+  .cl-anchored-arrow[data-side="left"] {
+    padding-right: calc(var(--cl-anchored-padding-x) + var(--cl-arrow-extent));
+  }
+
+  .cl-anchored-arrow[data-side="right"] {
+    padding-left: calc(var(--cl-anchored-padding-x) + var(--cl-arrow-extent));
+  }
+
+  /**
+   * Base UI positions this as its arrow element; ClaraLight never paints it.
+   * It is a measurement probe: Floating UI writes the already-clamped arrow
+   * offset onto it as inline `left`/`top`, and `AnchoredSurface` reads its box
+   * to place the tail. Sized so that clamp accounts for the real tail width.
+   */
+  .cl-anchor-probe {
+    width: var(--cl-arrow-width);
+    height: var(--cl-arrow-extent);
+    pointer-events: none;
+    visibility: hidden;
+  }
+
+
+  /**
+   * The entrance and exit: the surface grows out of its own tail, then returns
+   * to that same point.
+   *
+   * A dialog nudges into place — `--cl-enter-scale` is 0.95 for it, because a
+   * modal has no fixed point to grow from. An anchored overlay does: the tail's
+   * tip sits against the anchor and does not move while the surface opens, so
+   * the surface starts at **zero** and unfolds from that point. That is what
+   * makes the overlay read as pointing at its anchor instead of appearing near
+   * it, and it is why this is a second entrance rather than a value change to
+   * `.cl-enter-root`.
+   *
+   * No opacity leg on the way in, unlike `.cl-enter-root`: at scale 0 there is
+   * nothing on screen to fade, and the surface ClaraLight draws arrives opaque
+   * and grows. Opacity is what the reduced-motion fallback uses instead.
+   *
+   * The origin is not here. It is a measured length that only the component
+   * knows — where on the edge the tail actually landed — so `AnchoredSurface`
+   * writes it inline; see `src/lib/anchored.tsx`.
+   */
+  .cl-anchored-root {
+    transition: scale var(--cl-duration-enter) var(--ease-cl-spring-overlay);
+  }
+
+  .cl-anchored-root:has(> [data-ending-style]) {
+    transition-duration: var(--cl-duration-exit);
+  }
+
+  .cl-anchored-root:has(> [data-starting-style]),
+  .cl-anchored-root:has(> [data-ending-style]) {
+    scale: 0;
+  }
+
+  /**
+   * Reduced motion drops the growth — the one part that is movement — and keeps
+   * the overlay legible with a short fade at the reduced duration. Same split as
+   * the Flutter overlay, which reserves opacity for exactly this case.
+   */
+  @media (prefers-reduced-motion: reduce) {
+    .cl-anchored-root {
+      transition: opacity var(--cl-duration-reduced) var(--ease-cl-out);
+    }
+
+    .cl-anchored-root:has(> [data-starting-style]),
+    .cl-anchored-root:has(> [data-ending-style]) {
+      scale: none;
+      opacity: 0;
+    }
+  }
+}

package/styles/base.css

@@ -0,0 +1,309 @@
+/**
+ * ClaraLight Design — component primitives.
+ *
+ * Tokens live in `theme.css`. This file holds the handful of behaviours that
+ * are part of the design language itself and are too structural to express as
+ * a Tailwind class string: the signature press interaction, the frosted
+ * floating surface, and the focus ring.
+ *
+ * Kept as CSS rather than utilities so a component's class list stays
+ * readable and the physics stay in one place.
+ *
+ * Everything here is used by every build. What only one or two components need
+ * ships beside them instead — `anchored.css` for Popover and Tooltip,
+ * `tooltip.css` for the shared-tooltip morph, `scroll-area.css` for the scroll
+ * area's edges and scrollbars — so a copy-in project that skips those
+ * components does not carry their CSS. The npm entry point pulls in all four.
+ *
+ *   @import "tailwindcss";
+ *   @import "@claralight-design/react/styles.css";
+ */
+
+/* Tailwind's built-in shadow compiler expands token values into literal
+ * --tw-shadow declarations. Keep these public utilities runtime-bound so a
+ * scoped --shadow-* override also reaches Squircle's SVG effect reader. */
+@utility shadow-frost {
+  box-shadow: var(--shadow-frost);
+}
+
+@utility shadow-panel {
+  box-shadow: var(--shadow-panel);
+}
+
+@utility shadow-dialog {
+  box-shadow: var(--shadow-dialog);
+}
+
+@layer components {
+  /* -------------------------------------------------------------------------
+   * Press
+   * ---------------------------------------------------------------------- */
+
+  /**
+   * The signature ClaraLight press:
+   * the control scales *up* while held, then springs back with overshoot on
+   * release.
+   *
+   * CSS picks transition values from the state being entered, which is exactly
+   * the behaviour we want and needs no JS:
+   *
+   *   press    -> element becomes :active          -> 170ms easeOutQuart
+   *   release  -> element stops being :active      -> 550ms spring
+   *
+   * The two legs therefore live in different rules. Overriding the duration
+   * through custom properties keeps a single `transition` shorthand valid
+   * instead of fighting `transition-property` ordering.
+   *
+   * Set `--cl-press-scale` using the size tokens so shorter controls move
+   * further in relative terms and every size feels equally responsive.
+   */
+  .cl-press {
+    --cl-press-scale: var(--cl-press-scale-lg);
+    --cl-press-duration: var(--cl-duration-release);
+    --cl-press-ease: var(--ease-cl-spring-press);
+
+    transition:
+      color var(--cl-duration-press) var(--ease-cl-out),
+      background-color var(--cl-duration-press) var(--ease-cl-out),
+      border-color var(--cl-duration-press) var(--ease-cl-out),
+      box-shadow var(--cl-duration-press) var(--ease-cl-out),
+      opacity var(--cl-duration-press) var(--ease-cl-out),
+      outline-color var(--cl-duration-fast) var(--ease-cl-out),
+      transform var(--cl-press-duration) var(--cl-press-ease);
+  }
+
+  /* Disabled shaped children can still leave their wrapper :active when
+   * pointer-events are suppressed. Guard both wrapped and standalone controls. */
+  .cl-press:active:not(:where(:disabled, [disabled], [data-disabled], [aria-disabled="true"])):not(:has(> :where(:disabled, [disabled], [data-disabled], [aria-disabled="true"]))) {
+    --cl-press-duration: var(--cl-duration-press);
+    --cl-press-ease: var(--ease-cl-press-in);
+    transform: scale(var(--cl-press-scale));
+  }
+
+  /**
+   * ClaraLight drops the scale entirely under reduced motion rather than
+   * shrinking it, and keeps the opacity/surface feedback.
+   */
+  @media (prefers-reduced-motion: reduce) {
+    .cl-press:active {
+      transform: none;
+    }
+  }
+
+  /* -------------------------------------------------------------------------
+   * Frosted floating surface
+   * ---------------------------------------------------------------------- */
+
+  /**
+   * Menus, popovers, dialogs and sheets. The blur, outline and shadow all
+   * consume theme tokens; Squircle handles their smooth-corner geometry.
+   */
+  .cl-frost {
+    background-color: var(--cl-frost);
+    -webkit-backdrop-filter: blur(var(--blur-frost));
+    backdrop-filter: blur(var(--blur-frost));
+    border: 1px solid var(--cl-outline-strong);
+    box-shadow: var(--shadow-frost);
+  }
+
+  /** Same layer, without the shadow — for surfaces stacked inside a panel. */
+  .cl-panel {
+    background-color: var(--cl-panel);
+    border: 1px solid var(--cl-outline);
+  }
+
+  /* -------------------------------------------------------------------------
+   * Smooth-corner root
+   * ---------------------------------------------------------------------- */
+
+  /**
+   * The wrapper `Squircle` renders around a clipped element.
+   *
+   * It exists because Lisse re-renders borders and shadows as SVG overlays,
+   * which have to be appended to a positioned element that tightly wraps the
+   * shape. Two consequences worth knowing:
+   *
+   * 1. **Transforms belong here, not on the shape.** The overlays are siblings
+   *    of the clipped element, so anything that moves the shape without moving
+   *    the wrapper tears the 1px border away from the edge. The press scale and
+   *    the dialog entrance therefore live on this element, which also reads
+   *    better: fill, border and shadow scale as one object.
+   *
+   * 2. **The focus ring lives here too**, because `clip-path` crops `outline` to
+   *    nothing on the shape itself — measured, a 2px ring at 2px offset goes
+   *    from 436 lit pixels to 0. `:has()` lets the browser's own
+   *    `:focus-visible` heuristic drive it, so there is no JS focus state and
+   *    clicks still do not flash a ring.
+   *
+   * The radius is carried in a custom property so the ring clears the shape at
+   * every radius token; `Squircle` sets it.
+   */
+  .cl-squircle-root {
+    border-radius: calc(var(--cl-squircle-radius, 0px) + var(--cl-focus-offset));
+    outline: var(--cl-focus-width) solid transparent;
+    outline-offset: var(--cl-focus-offset);
+    /*
+     * Deliberately no `transition` here. `.cl-press` and `.cl-squircle-root`
+     * very often sit on the same element, and a second `transition` declaration
+     * wins by source order — which silently replaced the press spring with an
+     * outline fade. `.cl-press` owns the transition and lists `outline-color`
+     * alongside its own properties.
+     */
+  }
+
+  .cl-squircle-root:has(> [data-cl-squircle]:focus-visible) {
+    outline-color: var(--cl-accent);
+  }
+
+  /**
+   * Text fields and selects take focus on click, and the user needs to see which
+   * field got it, so they cannot use `:focus-visible`.
+   */
+  .cl-squircle-field:has(> [data-cl-squircle]:focus) {
+    outline-color: var(--cl-accent);
+  }
+
+  /* -------------------------------------------------------------------------
+   * Floating-layer entrance
+   * ---------------------------------------------------------------------- */
+
+  /**
+   * Base UI observes animations on the popup element when deciding when to
+   * unmount. ClaraLight deliberately animates the wrapper so the fill, SVG
+   * outline and shadow stay together, which puts the visible transition one
+   * level above that observer.
+   *
+   * This non-visual animation is the bridge between the two contracts. It runs
+   * only while Base UI marks the popup as ending and animates a custom property,
+   * never opacity, transform or layout. The wrapper remains the only thing that
+   * moves; Base UI now has a real animation on the popup whose completion it
+   * can await before `forceUnmount`.
+   */
+  @keyframes cl-overlay-exit-sentinel {
+    from {
+      --cl-overlay-exit-sentinel: 0;
+    }
+    to {
+      --cl-overlay-exit-sentinel: 1;
+    }
+  }
+
+  .cl-exit-sentinel[data-ending-style] {
+    animation: cl-overlay-exit-sentinel var(--cl-duration-exit) linear both;
+  }
+
+  /**
+   * Menus, popovers, dialogs and sheets.
+   *
+   * The transition runs on the **wrapper**, not on the popup, because the popup
+   * is the clipped element and the SVG border and shadow overlays are its
+   * siblings on the wrapper. Scaling the popup alone would leave the 1px border
+   * and the shadow at their final size — 5% of a 512px dialog is 25px, which is
+   * very visible over a 250ms entrance.
+   *
+   * Base UI drives this from the popup's `data-starting-style` /
+   * `data-ending-style`; `:has()` lifts that state onto the wrapper so the whole
+   * assembly — fill, border and shadow — moves as one object.
+   *
+   * Two durations, because a scrim that takes as long as the spring makes the
+   * page behind it feel stuck. The ClaraLight springs are `Curve` equivalents,
+   * so `linear()` encodes the shape and the component owns the timing.
+   */
+  .cl-enter-root {
+    transition:
+      opacity var(--cl-duration-surface) var(--ease-cl-out),
+      scale var(--cl-duration-enter) var(--ease-cl-spring-overlay);
+  }
+
+  .cl-enter-root:has(> [data-starting-style]),
+  .cl-enter-root:has(> [data-ending-style]) {
+    opacity: 0;
+    scale: var(--cl-enter-scale);
+  }
+
+  .cl-enter-root:has(> [data-ending-style]) {
+    transition:
+      opacity var(--cl-duration-surface) var(--ease-cl-out),
+      scale var(--cl-duration-exit) var(--ease-cl-spring-overlay);
+  }
+
+  /**
+   * A layer whose geometry belongs to `useSurfaceMorph`.
+   *
+   * The 5% nudge belongs to a layer that has no fixed point to grow from. A layer
+   * that has one is carried by a projective quad, and the nudge would be a second,
+   * coarser claim on the same geometry — measured through it, the morph's own
+   * resting box lands 5% small, and therefore that far off the trigger.
+   *
+   * Opacity moves here for the same reason: the morph reveals the content from
+   * the same progress that carries the geometry, so the two legs cannot disagree.
+   * Left to a transition, the `ease-out` fade would empty the layer in the first
+   * half of a dismissal and leave the collapse back to the trigger unwatchable.
+   *
+   * Declared in the markup rather than set from the effect that drives the morph,
+   * because *changing* a computed `scale` is itself what starts the transition
+   * above: a component that reported itself as morphed one frame late would
+   * animate the nudge it was replacing. Present from the first style resolution,
+   * neither value changes and neither transition starts. This block has to stay
+   * after the two above it — it replaces their `transition` at equal specificity.
+   *
+   * Scoped to `no-preference` so reduced motion keeps the fade it is asking for,
+   * which is the CSS leg with no geometry underneath it.
+   */
+  @media (prefers-reduced-motion: no-preference) {
+    .cl-enter-root.cl-morph,
+    .cl-enter-root.cl-morph:has(> [data-starting-style]),
+    .cl-enter-root.cl-morph:has(> [data-ending-style]) {
+      transition-property: scale;
+      transition-duration: var(--cl-duration-enter);
+      transition-timing-function: var(--ease-cl-spring-overlay);
+      opacity: 1;
+      scale: none;
+    }
+  }
+
+  /* The dialog/select wrapper also fades for `--cl-duration-surface`; its
+   * sentinel has to cover that longer leg, not just the 110ms scale return. */
+  .cl-enter-root > .cl-exit-sentinel[data-ending-style] {
+    animation-duration: var(--cl-duration-surface);
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    .cl-enter-root {
+      transition: opacity var(--cl-duration-reduced) var(--ease-cl-out);
+    }
+
+    .cl-enter-root:has(> [data-starting-style]),
+    .cl-enter-root:has(> [data-ending-style]) {
+      scale: none;
+      opacity: 0;
+    }
+  }
+
+  /* -------------------------------------------------------------------------
+   * Focus
+   * ---------------------------------------------------------------------- */
+
+  /**
+   * ClaraLight marks focus with the accent color. Uses `outline` rather than a
+   * ring so the indicator never shifts layout and survives `overflow: hidden`
+   * ancestors, and stays visible on both schemes because accent is the same
+   * blue in each.
+   *
+   * Two variants, because the trigger differs:
+   *   cl-focus        buttons and other pointer-activated controls, which
+   *                   should not flash an indicator on mouse click
+   *   cl-focus-field  text fields and selects, where focus follows the click
+   *                   and the user needs to see which field took it
+   */
+  .cl-focus,
+  .cl-focus-field {
+    outline: var(--cl-focus-width) solid transparent;
+    outline-offset: var(--cl-focus-offset);
+  }
+
+  .cl-focus:focus-visible,
+  .cl-focus-field:focus {
+    outline-color: var(--cl-accent);
+  }
+}

package/styles/fonts/README.md

@@ -0,0 +1,63 @@
+# Fonts
+
+`theme.css` names four preferred families. This package currently ships
+**no font files** — the token layer supplies platform fallbacks. Rendering and
+metrics depend on the fonts installed by the consumer; they are not guaranteed
+to match the preferred faces.
+
+## What the design language expects
+
+| Family | Role | Token | Source / license |
+| --- | --- | --- | --- |
+| MiSans | UI text, Chinese + Latin (variable) | `--font-sans` | [hyperos.mi.com/font](https://hyperos.mi.com/font) — MiSans 字体知识产权许可协议, free commercial use & redistribution |
+| Sarasa Mono SC | Numeric values and units | `--font-mono` | [be5invis/Sarasa-Gothic](https://github.com/be5invis/Sarasa-Gothic) v1.0.40 — SIL OFL 1.1 |
+| ChillDINGothic | Large display headings | `--font-display` | [Warren2060/ChillDIN-ChillDINGothic](https://github.com/Warren2060/ChillDIN-ChillDINGothic) v1.300 — SIL OFL 1.1 |
+| Clara Serif Pro | Optional serif, not in the default ramp | `--font-serif` | Obtain the font and verify its license before redistribution |
+
+Check the license accompanying each actual font file before shipping it.
+
+## To ship them
+
+1. Obtain licensed font files from their upstream sources and convert to
+   woff2 for web delivery. Keep a variable version when the required weight
+   range and download size justify it.
+
+2. Subset for the languages the application supports. Preserve required CJK
+   coverage; use separate `@font-face` declarations with `unicode-range`
+   splits where useful. Do not assume an upstream file is already subset.
+
+3. Add the files in this directory (or a CDN), create the corresponding
+   `@font-face` stylesheet, and import it from `index.css`.
+
+## MiSans' wght axis is not standard
+
+Verify the named instances in the exact MiSans VF file you ship. The following
+mapping has been used for MiSans files with non-standard weight positions;
+it is not a guarantee for every release:
+
+| CSS `font-weight` | MiSans `wght` axis | Named instance |
+| --- | --- | --- |
+| 400 | **330** | Regular |
+| 500 | **380** | Medium |
+| 600 | **450** | Demibold |
+| 700 | **520** | Semibold |
+
+For a file with this mapping, axis position 600 is above Semibold, not
+Demibold. If explicit axis settings are needed, define the mapping as tokens
+in `theme.css`, then consume them rather than repeating axis values:
+
+```css
+/* Instead of relying on font-weight alone. */
+.cl-weight-title {
+  font-variation-settings: "wght" var(--cl-font-axis-title);
+}
+```
+
+Because `font-variation-settings` is a single property, the token ramp's
+`--text-*--font-weight` values are the *intent* (700/600/500/400). They land
+according to the loaded font's metadata; on fallback fonts the browser uses
+the available weights. The example axis token above is not shipped yet.
+
+Rather than hand-maintaining a utility per step, add a
+`@utility cl-wght-{400,500,600,700}` set in `theme.css` that maps to
+330/380/450/520 during the font drop-in.

package/styles/index.css

@@ -0,0 +1,28 @@
+/**
+ * ClaraLight Design — full stylesheet for npm consumers.
+ *
+ * Registry (copy-in) consumers import these files directly instead, and take
+ * only the ones their components need, so the files stay the single source of
+ * truth for both paths. The npm package cannot make that choice per consumer,
+ * so it imports all of them.
+ *
+ *   @import "tailwindcss";
+ *   @import "@claralight-design/react/styles.css";
+ */
+
+@import "./theme.css";
+@import "./base.css";
+@import "./anchored.css";
+@import "./tooltip.css";
+@import "./scroll-area.css";
+
+/**
+ * Tailwind v4 does not scan `node_modules`, so a consumer importing the built
+ * package would otherwise get components with every utility class stripped.
+ * `@source` is resolved relative to this file, which puts it at the package
+ * root next to `dist/`.
+ *
+ * Registry consumers do not need this: their copied components live inside the
+ * project and are scanned automatically.
+ */
+@source "../dist";