@flikk/ui 1.0.0-beta.3 → 1.0.0-beta.31

package/CHANGELOG.md

@@ -0,0 +1,1281 @@
+# Changelog
+
+All notable changes to Flikkui will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [1.0.0-beta.31] - 2026-07-31
+
+### Breaking Changes
+
+- **Icon library swapped: `@heroicons/react` → `@phosphor-icons/react`** — The required icon peer dependency is now Phosphor (`>=2.1.0`); Heroicons is no longer used anywhere in the library. Migration for consumers: `yarn remove @heroicons/react && yarn add @phosphor-icons/react`. **No component API changes** — every icon slot stays `ReactNode`, so icons you pass in (from any library) keep working; only the *built-in* glyphs (chevrons, dismiss ✕, check marks, status icons, etc.) changed shape from Heroicons to the visually close Phosphor equivalents at `regular` weight (`bold` where the old icons used `strokeWidth≥2`, replacing the old `24/solid` uses — one consistent weight voice). Rationale: the Figma design kit standardised on the Phosphor library, and this aligns code with design 1:1. Bundle note: Phosphor modules carry all six weights (~3–6× per icon, ~10–15 KB gzipped total for the ~25 built-in chrome icons); the generative icon vocabulary (`DEFAULT_ICONS`) keeps its library-agnostic names, so generative specs and `generative.schema.json` are unchanged.
+
+- **Color role `neutral` renamed to `mono`** — The gray/low-emphasis color role is now `mono` everywhere: the prop value (`color="mono"` on Button, Badge, Alert, Toast, KPI, Metric, Link, Spinner, CustomCursor), the `SemanticColor` / `ButtonColor` unions, and the CSS variables (`--color-mono-50…950`, `--color-mono`, `--color-mono-contrast`). The old name collided with Tailwind's own `neutral` color palette — mapping `neutral` in `tailwind.preset.cjs` shadowed Tailwind's real neutral so consumers couldn't reach it, and it blocked the goal of every role being usable as a shorthand (`bg-mono`, `bg-primary`, …) without stealing a Tailwind palette name. The preset now maps `mono` and no longer maps `neutral`, so `bg-neutral-*` / `bg-slate-*` / `bg-zinc-*` all resolve to Tailwind's real palettes again. There is **no `neutral` alias** at the prop level. Migration: replace `color="neutral"` → `color="mono"` and `var(--color-neutral-*)` → `var(--color-mono-*)`. Note: `--color-neutral-*` still resolves (to Tailwind's own neutral, a near-identical gray in the default theme) but no longer tracks the themed role — use `--color-mono-*` for the role.
+- **Charts — ~25 dead props removed from the public API** — `BarChart`, `StackedBarChart` and `AreaChart` each declared `extends StandardVisualProps` with no `Omit`. That interface is the *union* of every chart's visual props, so each chart inherited the others': they type-checked, appeared in the generative schema (an LLM could emit them), and were never read. `BaseChartProps` doesn't extend `HTMLAttributes` and the spread targets are plain `<div>`s, so they couldn't even be forwarded — `<BarChart curved />` reached a div as an unknown attribute. Each chart's props are now narrowed with `Omit` to what it implements, matching what `LineChart`/`ComboChart`/`HorizontalBarChart` already did. Removed:
+  - **`BarChart`** — `orientation`, `curved`, `curveType`, `showDots`, `fillOpacity`, `showStroke`, `stacked`, `dotRadius`, `cellRadius`, `strokeWidth`. For horizontal bars use the new `HorizontalBarChart` (`orientation` was a second, non-functional way to ask for the same thing).
+  - **`StackedBarChart`** — the same ten, plus `gap` (segment separation is a fixed hairline, not a tunable) and `radius` (its `@deprecated` → `barRadius` mapping was never implemented, so unlike `BarChart`/`AreaChart`/`LineChart` it never worked at all).
+  - **`AreaChart`** — `barRadius`, `cellRadius`, `gap`.
+  - **`ComboChart`** — `fillOpacity`, `showStroke`, `cellRadius`. Its `SeriesType` is `'bar' | 'line'` with no area member, so the area-fill props had nothing to apply to.
+  - **`ScatterPlot`** — `variant`. Scatter points are flat single-colour marks; there is no gradient/minimal treatment to select.
+  - **`cellRadius` is gone library-wide** — it was declared "for heatmap cells" and `Heatmap` never referenced it.
+  - **Axis family** — `color` and `fontSize` are removed from `BaseAxisProps` and `AxisTickProps` (so from `XAxis`, `YAxis`, `ValueXAxis`, `CategoryYAxis`), and `color` from `HorizontalGrid`. Axis lines and labels are themed via CSS variables (`stroke-[var(--color-border)]`); `color` was accepted, defaulted to `"currentColor"`, and ignored, and `fontSize` had no implementation anywhere. Restyle an axis with `className`, or change the token.
+- **Charts — `CHART_DEFAULTS` and the exported `*_DEFAULTS` objects lost their dead keys** — each `*_DEFAULTS` spread `...CHART_DEFAULTS`, so every chart published a default for every other chart's props. They now list only what their component reads. `CHART_DEFAULTS` also drops `cellRadius`, `orientation`, and `radius` (nothing consulted the last one — the deprecated `radius` *prop* still works on `BarChart`/`AreaChart`/`LineChart`, falling back to `barRadius`/`dotRadius`). These objects are publicly exported, so reads like `BAR_CHART_DEFAULTS.curved` no longer compile.
+- **`AvatarGroup` — `spacing` prop removed** — The group now renders one fixed overlap (the former `"normal"`, `-ml-3`). The three-value scale was a styling axis with an inverted, confusing vocabulary — `"tight"` meant *more* overlap (`-ml-5`) and `"loose"` meant *less* (`-ml-2`), the reverse of how the words read — and it duplicated what `className` already does better. The `AvatarGroupSpacing` type is no longer exported. Migration: drop the prop; to restore a custom overlap, pass it through `className` (e.g. `className="[&>*+*]:-ml-5"`). Internal call sites that used `"loose"`/`"tight"` (`CalendarEvent`, Popover stories) now use the single default, so their avatars sit fractionally differently.
+- **`Segmented` — default width is now fit-content** — The control previously stretched to fill its parent by default (its `flex` root is block-level, so it spanned full width regardless of the `block` prop, which was effectively a no-op). It now shrinks to fit its segments by default, and `block` genuinely opts into full width — matching the documented `block` contract and the iOS/shadcn segmented-control convention. Migration: add `block` to any `Segmented` that should span its container.
+- **Control heights and button padding retuned — every form control and Button changes size** — No API change, but the default values move, so consumer layouts shift. Heights (`--form-min-h-sm/md/lg`) go from **32/40/48px → 32/36/40px**, an even 4px step where the old ramp jumped 8px; button horizontal padding (`--button-px-sm/md/lg`) goes from **12/12/20px → 10/12/14px**, a consistent +2 ramp (`sm` and `md` previously collided at 12px and `lg` was an outlier). This lands the ramp on the same scale Untitled UI and shadcn use, with our `lg` (40px) at the industry-standard default height. Blast radius is wider than the token names suggest: `--button-min-h-*` and `--button-icon-size-*` both alias `--form-min-h-*`, so this resizes every form control, every Button, and every icon-only Button. Icon-only `sm` stays 32×32, clear of WCAG 2.2 SC 2.5.8's 24×24 floor. `--form-px-*` is deliberately untouched (12/14/16) — controls get shorter but keep their horizontal padding. To keep the old sizing, override the three height tokens in your own CSS.
+- **`--radius-base` default is now 8px** (was 12px) — Every derived radius in the library scales from this one token, so the default theme is uniformly less round. Set `--radius-base: 12px` to restore the previous look.
+- **Default chart series colors are no longer the semantic status palette** — Multi-series charts previously drew from `primary`/`warning`/`success`/`danger` at two lightness steps, which meant a categorical series could read as a *status* (a red series looking like an error). They now resolve from the new dedicated `--color-chart-1…5` palette. An explicit `config[key].color` is unaffected and still wins, including the bare-token shorthand (`"success"` → `var(--color-success)`). To restore the old look, set the colors explicitly in `config`, or override `--color-chart-1…5`.
+- **`--hero-card-radius` retired** — `HeroCard` had its own radius token at 3× base (vs `Card`'s 1.5×) on the belief that it needed a rounder look. It is a *presentation* of Card, not a distinct container, so it now shares `--card-radius`. Per-instance overrides still work via `className`. Migration: if you set `--hero-card-radius`, move that value onto the HeroCard's `className` or override `--card-radius`.
+
+### Added
+
+- **AI — `AgentStatus`, `Reasoning` and `SourceCitation`** (`@flikk/ui/ai`) — `AgentStatus` is the single agent-activity-row primitive and owns the reasoning disclosure through a `mode` prop, so one component covers the three ways a chat surfaces the same row: a live status line (`Thinking… 4s`), a collapsible "show your work", and each step inside it. `mode` and the lifecycle `status` stay **orthogonal** — a reasoning block is itself active or settled. The reasoning body is not always a step list: `steps={[{label,status,duration}]}` renders an `<ol>` of nested rows, while `children` render **raw**, so prose and markdown stay valid HTML. `Reasoning` is a thin preset over `mode="reasoning"` (`Reasoning.Step` aliases a status row). `SourceCitation` renders inline citation chips with preview popovers. Both share one `StatusIndicator` glyph, whose active spinner is a CSS `animate-spin` comet — motion only does enter/exit, since a single-value `rotate` target flattens to a static transform. New public hook **`useElapsedTime`** powers `startedAt`: the duration ticks on its own while active, takes one exact final reading on settle, then freezes, and the clock is only read inside an effect so there is no `Date.now()` in render to hydrate-mismatch.
+- **`HorizontalBarChart`** (`@flikk/ui/charts`) — Categories run down the left, values extend right. It shares `BarChart`'s data model and none of its axis wiring (the value/category axes are swapped), so it ships as its own component rather than an `orientation` flag. Use it when category names are long or numerous, or when the chart ranks items — a column chart cannot fit "United Kingdom" under its axis. Three new shared axis primitives came with it, because the axis layer had no horizontal support at all: `ValueXAxis` (a value axis rendered horizontally, Heckbert nice ticks), `CategoryYAxis` (a category axis rendered vertically), and `VerticalGrid`. 🔴 Note the axis family splits by what an axis **measures**, not which way it points — `XAxis` is a category axis despite being horizontal.
+- **`LollipopChart`** (`@flikk/ui/charts`) — Stem-and-dot marks with a staggered entrance, an always-on stem gradient + soft glow, hover/keyboard-focus/pinned-selection states (controlled and uncontrolled `selected`/`defaultSelected`), and a dot↔pill morph that animates a single `rx`-interpolating `motion.rect`. Uses the shared `XAxis` and `X_AXIS_MARGIN` so its baseline aligns with every other chart.
+- **`Button` — `iconStart` / `iconEnd`** — Button had no icon prop at all: `children` covers icons via the flex gap, which holds for hand-written code, but **a generative UI spec is JSON** — it can *name* an icon, never pass a React element — so an LLM literally could not put an icon on a button. This is the "one contract, two front doors" pattern §2 already established for collection `items` arrays and Card's flat `title`/`subtitle` slot-props. Button deliberately takes the **icon slots only** and *not* `contentStart`/`contentEnd`: an icon can be named, an arbitrary `ReactNode` cannot, so content slots would buy the generative path nothing. Composite stays the idiom and every existing call site is untouched — pass neither slot and `children` renders exactly as before. `theme.iconSizes` uses `[&>svg]:size-*` so a bare `<SearchIcon />` with no `className` still lands at the right size per button size (14/16/20 for sm/md/lg); a caller's own `className` still wins. The icon wrappers are `aria-hidden`, so the accessible name stays the label alone.
+- **`Tooltip` — controlled mode** — New `isOpen` / `defaultIsOpen` / `onOpenChange` props, plus a `recalcTrigger` escape hatch for triggers that move without firing a scroll or resize event (a dragged `Slider` thumb, for instance). `aria-describedby` is now merged with any existing value instead of clobbering it.
+- **`Modal` — `darkMode` prop** — Mirrors `Button`'s: applies the `dark` class to the modal container so a modal can render dark while the page is light.
+- **`InputAddress` — `showCountrySelector` / `showPostalCode`** — Lets either field be hidden for address formats that don't use them. Because the fields render as one merged perimeter, the corner radii are position-aware: the last visible field carries the bottom corners, and a lone bottom field spans the full row instead of splitting into two columns.
+- **`InputOTP` — `charset` prop (`numeric | alphanumeric`)** — Drives the sanitizer, `pattern` and `inputMode` together, so the on-screen keyboard, the accepted characters and the validation hint can't drift apart.
+- **`OfflineIndicator` — `action` prop** — Takes `{ label, onClick }` for a link-styled button (mirroring `Toast`'s `action`) or any `ReactNode`. Also gains full-bleed banner positions and reduced-motion fallback variants.
+- **`CommandPalette` — `onCommandSelect(id)`** — Fires alongside each command's own `onSelect`, so a single top-level callback can observe selection (this is what lets the generative registry bind commands through the standard action mechanism instead of synthesizing per-item callbacks).
+- **`Checkbox` / `Radio` — selection ripple** — A shared ripple animation on check, with reduced-motion coverage.
+- **Preset theme "Ember"** — A third shipped theme: orange primary, zinc neutrals, Plus Jakarta Sans, pill geometry and a 24px base radius. Registered in the Storybook theme switcher alongside Iris and Jade.
+- **Four new themeable token systems** — (1) **Per-container padding**: `--card-px/py`, `--modal-px/py`, `--drawer-px/py`, `--metric-content-p-sm/md/lg`, so a theme can make the brand-visible containers roomier or tighter without touching every padded element in the library. (2) **Three-tier radius ceilings**: `--surface-radius-cap-xs/sm/lg` wrap every content-bearing container's derived radius in a `min()`, so a theme chasing pill *controls* at a large `--radius-base` can't round a padded container past what its own padding can absorb (a curve-vs-padding collision that visually eats into header text). Controls stay uncapped — going fully pill there is correct. (3) **Per-role font sizes**: `--card-title-size`, `--modal-title-size`, `--drawer-title-size`, `--page-heading-title-size`, `--section-title-size`, `--metric-value-size-*`, `--kpi-value-size-*` — `--font-scale` can only resize the *whole* UI, so these let a theme resize a single role. Each defaults to a `--text-*` rung, so `--font-scale` still flows through. (4) **`--color-chart-1…5`**: a categorical chart palette decoupled from the semantic status colors. Sixteen components whose radius/padding/title-size had drifted into a bare uncapped `calc()` were wired onto these systems.
+- **Generative UI — curated set expanded from 32 to 66 components** — Forms were entirely uncurated before this (Input, Select, Combobox, Textarea, Checkbox, Switch, Slider, InputOTP, TimePicker, InputDate, InputCounter, InputTag), joined by 16 more Core/Data Display entries (Spinner, Skeleton, Link, Kbd, DotSeparator, Icon, Pagination, Message, MenuItem, Calendar, GanttChart, AspectRatio, ButtonGroup, Masonry, ScrollArea, HeroCard), `Tree` and `CommandPalette`, and the five remaining charts the manifest had deferred as "bespoke prop systems" (RadarChart, ScatterPlot, FunnelChart, ActivityRings, Heatmap). Notable: `Calendar`'s schema carries ISO strings with a `render:` wrapper coercing string→Date inbound and Date→ISO outbound; `CommandPalette` forces `isOpen: true` (it renders through the shared `Overlay`, so a spec node is always a full-screen modal) and supports only the flat `CommandItem[]` shape.
+- **`flikkui init` CLI** (separate `flikkui` package, `npx flikkui init`) — Implements the setup command the installation docs have long referenced. Detects framework, package manager and Tailwind; installs `@flikk/ui@beta` plus any missing required peers; injects the `styles.css` (and optional preset theme) import; and wires the Tailwind v4 dark variant. Zero runtime dependencies. Every project ends in exactly one explicit outcome — auto-wired (Next App/Pages Router, Vite), a named-framework manual snippet (CRA, Remix/RR7, Gatsby, Astro), a generic snippet, or a refusal with a stated reason (no `package.json`, React Native/Expo, React < 18). Theme imports are capability-checked against the installed package version. 128 unit tests + fixtures. Tracked in `packages/cli/CHANGELOG.md`.
+- **Figma design-kit generator (`yarn build:figma-tokens`)** — Design-ops tooling, deliberately **not** wired into `yarn build`. Parses `src/styles/theme.css` and emits `dist/figma-variables.json`: variables split across `Flikk/Primitives` (single mode) and `Flikk/Semantic` (Light/Dark), plus shadow effect styles derived from the `--elevation-surface-*` ladder. Mode-dependence is **derived, not curated** — a token is Semantic iff `.dark` overrides it *or it transitively references something that is*. Unknown value forms are a **hard failure (exit 1), never a guess**: the evaluator understands exactly four computed families, so adding a new one must break this build. See `docs/figma-component.md`.
+
+- **`Avatar` / `AvatarGroup` — `size` now accepts an exact pixel number** — `size={30}` sizes the circle to exactly 30px alongside the existing `"xs" | "sm" | "md" | "lg" | "xl"` rungs (`AvatarSize = AvatarSizeToken | number`; the new `AvatarSizeToken` type is exported). The type already admitted `number` but no implementation backed it: the theme's `Record<AvatarSize, string>` lookup returned `undefined` for a number, so `size={30}` type-checked and rendered an avatar with **no size class at all**. This is a fix as much as a feature. Note that `className="size-[30px]"` is not an equivalent workaround — the shipped `styles.css` only contains classes found in this library's own source and `tailwindcss` is an optional peer, so an arbitrary size utility resolves to nothing for consumers who don't run Tailwind themselves. Geometry is exact; decorations (glyph, status dot, verified badge, text gap) snap to the nearest rung (30 → `sm`). Token sizes render byte-for-byte identical to before. Implementation note: the circle now always carries the class `size-[var(--avatar-size)]` with the value supplied inline via the `--avatar-size` custom property, so anything targeting the old per-token `size-[var(--avatar-size-md)]` class in CSS will no longer match.
+- **Preset themes (`flikkui/themes/*`) + first theme "Iris"** — The library now ships swappable preset theme files: plain CSS-variable override files imported after `styles.css` (`import 'flikkui/themes/iris.css'`) — no config, no JS, no rebuild. The default look is unchanged and needs no import ("Neutral" is baked into `styles.css`). **Iris** restyles the whole library: Tailwind indigo primary ramp, slate-tinted neutrals and borders, Bricolage Grotesque type, and a rounder 16px base radius — with its own dark-mode values (theme files carry explicit `.dark` overrides inside `@layer theme` so dark mode composes correctly). Storybook gets a toolbar theme switcher (paintbrush icon) that live-swaps themes, including combined with dark mode. Custom themes are the same file format — see the Preset themes section in `docs/INSTALLATION.md`. A second preset, **Jade**, reshapes geometry and type as well as color: Tailwind emerald primary, warm stone neutrals (hueless in dark), Poppins on a 14px text scale, and pill-leaning controls (`--radius-base: 20px`, taller form/button heights with wider padding).
+- **Chip-tier padding tokens — themeable Badge / Pill / Tag / Kbd spacing** — The four small "chip" controls now read their padding from CSS variables instead of hardcoded Tailwind literals, so a theme can grow (or tighten) them alongside its buttons and inputs — the same reasoning as the per-component container padding and type-role tokens (a global knob can't make *only* badges roomier). New tokens: `--badge-px-sm/md`, `--badge-py-sm/md`, `--badge-pill-px-sm/md`; `--pill-px-sm/md/lg`, `--pill-py-sm/md/lg`; `--tag-px-sm/md`, `--tag-pl-md`, `--tag-py-sm/md`; `--kbd-px-sm/md`. Defaults are byte-for-byte identical to the previous literals, so the default theme is unchanged. Radius needs no new token — `--badge-radius` now derives from `--radius-base` (`calc(var(--radius-base) * 0.75)`, was a hardcoded `6px` that silently ignored the base, so a large `--radius-base` now rounds badges too), Kbd already derived, and Pill/Tag are intrinsic `rounded-full`. The `jade` and `ember` presets set these so their badges/pills/tags match their spacious geometry. Chip **gap** and Kbd **height** stay literal for now.
+- **`--font-scale` — one-knob type scale** — The base theme now defines the whole Tailwind `--text-xs…9xl` ramp as `calc(<tailwind default> * var(--font-scale))`. At the default `1` every utility is byte-for-byte Tailwind (`text-sm` = 14px); a theme or consumer sets a single factor (Jade: `0.875` → 14px-based text) and the entire ramp plus line-heights follow. Each step is `round()`ed to a whole pixel so scaled sizes stay clean (13px, not 13.125px). Text-only — spacing and px geometry tokens are unaffected.
+- **Control type-size tokens — themeable Button / Input / Segmented label size** — The control tier had every *box* axis tokenised (`--form-min-h-*`, `--form-px/py-*`, `--form-radius`) while its *type* stayed a hardcoded `text-sm` / `text-base` in each `.theme.ts`, so a theme could retune a control's height and padding but never its label. New tokens: `--form-text-size-sm/md/lg` with `--button-text-size-*` and `--segmented-text-size-*` aliasing it (mirroring how `--button-min-h-*` already aliases `--form-min-h-*`), each paired with a `--*-line-height-*` token. Consumed by Button, Segmented, and — via `formsBaseTheme.sizes.*.text` — Input, Select, Textarea, Combobox, DatePicker, DateRangePicker, TimePicker and RichTextEditor. Defaults are byte-for-byte identical to the literals they replaced (sm/md 14px/20px, lg 16px/24px) and each points at a `--text-*` rung, so `--font-scale` still flows through and the default theme is visually unchanged apart from the Segmented fix below. Note the ramp is deliberately **two rungs across three sizes** — sm and md share 14px and only lg steps to 16px; the small sizes are separated by box, not type.
+- **`InputOTP` — `size` prop (`sm | md | lg | xl`)** — `InputOTP` was the only text-entry form control without one, so an OTP could not be lined up with an adjacent `sm` or `lg` `Input`. `sm`/`md`/`lg` resolve to the same heights as the equivalent `Input` size; **`xl` is a new OTP-only rung** (48px in the default theme) for standalone verification screens where the code is the focus of the page. Defaults to `lg`. New tokens: `--otp-slot-size-sm/md/lg/xl`, `--otp-text-size-*` and `--otp-line-height-*`. `sm`/`md`/`lg` alias `--form-min-h-*` and `xl` derives from `--form-min-h-lg` (`calc(… * 1.2)`), so all four track a theme that retunes the form ramp — a hardcoded `xl` would have rendered *smaller than `lg`* under the `jade` (36/44/52) and `ember` (40/48/56) presets. The digit type ramp (16/16/18/20px) deliberately runs one rung hotter than form body text: an OTP numeral is a display glyph, not label text. The digit and the caret now scale with the slot; both were previously fixed at 18px and 20px regardless of size.
+- **`DotPattern` — `fadeDirection="center"`** — A new inverse-radial fade: dots stay solid toward the edges and fade out in the center (the opposite of `"radial"`), producing a vignette that keeps the content area behind the pattern clear. Tunable via `fadeSize` like the other directions. `DotPatternFadeDirection` is now `"radial" | "center" | "top" | "bottom" | "left" | "right"`.
+
+### Changed
+
+- **`InputOTP` slots are no longer responsive** — They previously stepped from `--form-min-h-md` to `--form-min-h-lg` at the `sm` breakpoint, which cannot coexist with an explicit `size` prop. The default `size="lg"` renders identically to the previous desktop output; narrow viewports now render at the same size rather than one rung smaller, and can opt into `size="sm"` — something that was impossible before. **Breaking for custom themes:** `InputOTPTheme.inputGroupStyle` (a single string) is replaced by `inputGroupSizes` and `charSizes`, both `Record<InputOTPSize, string>`. This only affects consumers passing a custom `theme` to `InputOTP`, and it is a compile-time type error, never a silent visual change.
+- **`--color-neutral` + `--color-neutral-contrast`** — neutral gains the same bare-default machinery as the semantic hues (900 in light, 200 in dark, auto-derived contrast text). `Button`'s filled-neutral now uses the token pair instead of hand-picked rungs + hardcoded `text-white`/`dark:` inversions (its light-mode per-color border classes were also removed — dead code, always beaten by the universal `border-black/25` edge; the live color-matched `dark:border-*` classes remain).
+- **Muted/placeholder/disabled text — one token source, no dark-mode bypasses** — `--color-text-placeholder` and `--color-text-muted` are now alpha-derived from `--color-text-primary` via `color-mix` (40% / 57% light, 40% / 50% dark), so they automatically track the theme's text color in both modes and on any surface. The ~30 hardcoded `dark:text-[var(--color-neutral-N)]` / `dark:placeholder:text-[var(--color-neutral-500)]` classes scattered across forms, CommandPalette, Calendar, Message, Pagination, Sidebar and the date/time pickers are removed — they bypassed the tokens and pinned dark text to neutral ramp rungs, which broke preset themes (an Iris dark placeholder rendered slate-blue; same disease as the Segmented fix below). Dark `--color-text-disabled` is now `neutral-600` (the value every picker was overriding to) instead of `neutral-400`. Visual deltas in the default theme are minor: dark helper text slightly dimmer, dark input icons slightly brighter (the two camps now share one muted value), dark disabled text dimmer.
+- **`Table` — smaller row-expand toggle** — The data-driven expand/collapse control was a full 32px outlined `Button` (form-control height), which read as oversized against row content. It's now a compact ~24px borderless ghost icon button (`variant="ghost"`, `size-6`), matching the conventional table expand affordance. Behavior and a11y labels are unchanged.
+- **`--color-success` default is now the `-600` step** (was `-500`) — matches danger/warning, and the auto-derived white `-contrast` text now passes WCAG AA on filled success surfaces (white on success-500 was ~2.7:1). Filled success Badges/Alerts/Toasts render a slightly darker teal; the full 50–950 ramp is unchanged.
+- **Dark glass gradients moved onto the surface ladder** — `--glass-gradient-outer/inner` dark values now reference `--surface-1/3/4` instead of the deprecated `--color-background-secondary/tertiary` aliases (visually near-identical), so the aliases' scheduled removal can't break `GlassEffect` in dark mode.
+- **`InputOTP` rebuilt around a single native input** — The control was N separate `Input` elements; it is now one invisible native input overlaying the visual slots. This fixes paste-with-separators truncation (`123-456` no longer loses characters) and caret drift, and is what makes the new `charset` prop able to drive sanitizer, `pattern` and `inputMode` from one place. Public API is otherwise unchanged.
+- **`Slider` — drag tooltip rebuilt on the shared `Tooltip`** — The bespoke SVG liquid-lens filter and custom drag bubble are replaced by the shared `Tooltip` (in its new controlled mode, with `recalcTrigger` so the tooltip follows the dragged thumb). The solid glass-look thumb styling moved into the theme file, so it's overridable like every other component's.
+- **`Link` — primary variant tints from the base `--color-primary` token** — Was pinned to the fixed `-600`/`-300` rungs, so it ignored whatever rung a theme parks the token at. Under every shipped preset this resolves to `primary-600` in light — identical to before — and one rung deeper in dark. The default Neutral theme, where primary aliases the mono ramp, renders a darker link than before. The animated underline is also offset 1px so it clears descenders.
+- **Form dropdowns — one option treatment across `Select` / `Combobox` / `Mention` / `InputTag`** — Combobox and InputTag rendered full-bleed square option rows while Select and Mention rendered inset rounded ones. All four already shared `formsBaseTheme.dropdownStyles`; the base simply withheld the two classes the treatment needs, so each call site re-decided it and two got it wrong. The `p-1` container inset and the option's `rounded-[var(--radius-base)]` now live in the shared base — which already assumed this treatment, since it sets `gap-0.5` between rows and draws an inset hairline ring on hover, neither of which reads correctly on a square full-bleed row.
+- **Press/hover feedback consolidated into one shared module** — `src/components/core/shared/interaction.animations.ts` (`createPressVariants` + press/release/hover transitions) is now the single source for Button, Pill and Badge; `Pill.animations.ts` is removed. Press-down is a fast ~80ms tween (feedback must be near-instant), release a stiff spring with slight overshoot. `Alert`, `DatePicker` and `SelectableCard` also drop their one-off transitions for the shared spring presets.
+
+### Removed
+
+- **Unused internal theme tokens** — deleted from `theme.css`; never consumed by any component nor documented: `--form-focus-ring-*`, `--form-outline-*`, `--glass-layer-*`, `--segmented-active-bg/-shadow`, `--chat-bubble-border-*`, all `--carousel-*`, the dead `--popover-*` set (shadow, border-width, backdrop-opacity, offsets, max-widths, paddings — `--popover-radius` stays), `--nav-item-min-h/-px/-py` (`--nav-item-radius` stays), the `--shadow-color-*` presets, and `--font-cursive` (its font was only ever loaded inside Storybook).
+
+### Fixed
+
+- **`PromptInput` — the invalid focus ring now uses the shared `--color-danger` token** — Its invalid state drew the `ring-4` glow from `--color-danger-500` in light mode, while every other form control (via `formsBaseTheme.states.invalid`) uses `--color-danger` (the 600 rung). Dark mode already agreed on both sides (`--color-danger-500` at 20%), so the two disagreed *only* in light — and the inset danger border on the very same line already used `--color-danger`, making the rule internally inconsistent as well. The light ring is now marginally deeper red and consistent with Input/Select/Textarea/OTP. No API change; the `dark:` value is untouched. Regression test added. This also lets the component share the Figma kit's single `Rings/Invalid` effect style instead of needing a one-off.
+- **`Segmented` — `size="lg"` now steps its label up to 16px** — Segmented's box tokens are straight aliases of the shared form ramp (`--segmented-min-h-*` → `--form-min-h-*`), but its type was pinned to `text-sm` at **all three** sizes, so `lg` grew its height and padding while the label stayed at 14px — out of step with Button and Input, which both step 14px → 16px at `lg`. `lg` labels now render at 16px/24px like every other large control. **The control's height is unchanged** (still 40px; the taller line-height fits inside the existing `min-h`), so this is a type fix, not a layout shift. `sm` and `md` are untouched. The Figma design kit's `Segmented item` `lg` variants were re-pushed to match. Regression test added.
+- **Dead props — five public props were accepted and typed but never read** — each silently did nothing when passed. All five are now implemented, with regression tests:
+  - **`ScatterPlot` — `legend`** — inherited from `StandardChartDisplayProps` but never destructured, so the legend was hardcoded to always-render-at-bottom and every value (`"top"`, `"bottom"`, `"none"`) did nothing. It now honours all three, resolved through the same shared `resolveLegendPosition` every other chart uses, satisfying the documented contract that ScatterPlot renders the shared `ChartLegend` from `legend`. **Behavior change:** an omitted `legend` now resolves to `"bottom"` for multi-category data and `"none"` for single-category — so a single-category scatter no longer shows a one-item legend by default. Pass `legend="bottom"` to keep it.
+  - **`Modal` — `darkMode`** — documented as applying the `dark` class to the container, but never destructured, so it fell through `...props` into `Overlay` (which doesn't declare it either) and dead-ended. It now applies `dark` to the modal container, matching the existing `Input`/`BarChart`/`LollipopChart` implementations of the same prop.
+  - **`Sidebar.Toggle` — `expandIcon` / `collapseIcon`** — destructured but unused; the toggle always rendered its hardcoded chevron. Both are now wired, falling back to the default chevron when omitted. Semantics are **action-based**, matching the button's own aria-label: `expandIcon` shows while the sidebar is *collapsed* (clicking expands), `collapseIcon` while *expanded*. A custom icon renders as-is — the default chevron's 180° flip is only applied to the chevron itself. The JSDoc, which described the opposite (state-based) meaning, was corrected.
+  - **`InputAddress` — `showCountrySelector` / `showPostalCode`** — typed but never read (the component has no rest spread, so they dead-ended entirely). Both now hide their field. Because the fields render as one merged perimeter, the radii are position-aware: the last visible field carries the bottom corners, and a lone bottom field spans the full row.
+  - **`ScatterPlot` — `gridClassName`** — destructured but unused, while `svgClassName`/`dotClassName`/`axisClassName` all worked. It now styles the grid lines (plumbed through the shared `YAxis`, which draws ScatterPlot's grid), matching `AreaChart`'s existing `gridClassName`.
+- **`tailwind.preset.cjs` — `bg-primary` now matches component colors** — Each semantic color's `DEFAULT` was pinned to a fixed rung (`primary-600`, `success-500`, …), so consumer shorthands like `bg-primary` resolved to a different color than the library's own components (which paint the bare `--color-primary` base — `-900` in the monochrome base theme, `-600` in a colored theme). DEFAULTs now point at the bare `var(--color-*)` base, so `bg-primary` equals what components render and follows the active theme and dark mode. Also pruned deprecated `background-quaternary/quinary` maps, added the surface ladder + `border-secondary`/`border-hover`, and corrected the `--form-radius`/`--button-radius` token names. The `@flikk/ui/theme.css` v4 entry's broken `dist` relative import and a stale `--form-rounded` token in `shadcn-compat.css` were fixed too.
+- **Dark-mode active scrollbar thumb color** — `--ui-scrollbar-thumb-active` used invalid mixed rgb syntax (`rgb(75 85 99, 0.75)`), so the declaration failed at computed-value time and the active thumb lost its intended dark tint. Now `rgb(75 85 99 / 0.75)`.
+- **`Badge` — `iconStart` no longer hugs the edge** — the icon wrapper applied a `-ml-1` optical tuck unconditionally, which cancelled the regular badge's 4px padding and left the icon ~1px from the border. The tuck is now pill-only (pills have the extra `pillSizes` padding to absorb it), mirroring the avatar slot's existing pill/non-pill conditional. Badge width with text-only content is unchanged.
+- **`PromptInput` — model-menu icon stacked above the label** — The model selector passed its icon inside `Dropdown.Item` children, where MenuItem's block-level `truncate` label span (plus Tailwind preflight's `svg { display: block }`) broke it onto its own line. The icon now goes through the proper `startContent` slot and renders inline with the label.
+- **`Dropdown` — menu gets a `max-w-[20rem]` cap** — A long item label stretched the menu unboundedly (MenuItem's `truncate` could never engage without a width bound). Long labels now ellipsize at 320px.
+- **`Dropdown.Trigger` — no longer overrides a `Button` trigger's styling** — The trigger injected a translucent `surface-hover` tint (on hover, and while the menu is open) onto whatever it wrapped. For a *filled* `Button` — which hovers via a `brightness` filter, not a `hover:bg-*` — that tint had nothing to override and instead replaced the solid fill, so a filled trigger (e.g. the chevron half of a filled split button) went see-through/dark on hover and mismatched its sibling. The tint is now skipped for `Button` children (Buttons are self-styled and bring their own hover/active/variant states); plain/custom trigger elements still get it. Fixes the `ButtonGroup` "Split Button" filled example.
+- **`Calendar` — consistent selected & hover styling across single/range modes** — Range start/end days had their own fill/text rules and no hover override, so hovering an endpoint fell through to the generic neutral day-hover (a muddy grey with poor contrast) and looked different from a single-selected day. Endpoints now route through `data-selected`, inheriting the exact same fill, text, top-border, and hover as a single-selected cell (one source of truth for "a selected day"). In-range (between) days no longer carry a bespoke hover either — they use the same base day-hover as normal days, so a hovered cell looks identical whether or not it sits inside a range.
+- **`Table` — jerk at the end of row collapse** — Expanding rows use a height-animating container inside a full-width colspan `<td>`. That cell was picking up ~20px of vertical padding from the table's `[&_td]:py-*` descendant rule (which out-specifies the cell's own `p-0`), so the cell held a ~21px residual height after the animator had already collapsed to 0 — then snapped to 0 when the row unmounted, jerking the rows below. The expanded cell now forces `!p-0` so it tracks the animator down to ~0 (mirrors Accordion, where the animating container carries no padding and the inner content owns it). Padding for expanded content is owned by `expandedRowRender`, as before.
+- **`Segmented` — dark-mode background no longer collides with consumer utilities** — The theme hardcoded raw Tailwind classes (`bg-neutral-100 dark:bg-neutral-900` on the track, `dark:bg-neutral-800` on the sliding indicator). These emit global class names that a consumer's own `bg-neutral-*` utility could override by source order, permanently pinning the control's background to one tone regardless of the `.dark` class. The track now paints from `--color-surface-sunken` and the indicator from `--color-surface` (theme-aware CSS variables, no `dark:` variants), so it follows the theme correctly and can't collide. Visually unchanged. (PER-292)
+- **`Avatar` — status dot stranded outside the circle** — The dot was corner-anchored (`left-0 bottom-0`), but an avatar is a *circle*: its bounding-box corner sits ~41% further from the centre than the edge does, so the dot floated off the arc. It now centres on the circle's 45° point via one proportional rule (`left-[14.6%] bottom-[14.6%]` plus half-translates), which holds at every size including the new arbitrary numeric ones. Three further fixes fell out of the same pass: **(1)** the ring was a flat 2px at every rung, making it proportionally 3.3× heavier on `xs` than `xl` — dot and ring now ramp together, holding the badge's total footprint near 30% of the avatar across the ladder (was 42%→25%); **(2)** the `offline` dot moved off `--color-text-muted` — the text tokens are `color-mix` alpha derivations, so as a *fill* the dot went translucent and the photo showed through; it now uses `--color-mono-500`, the only rung clearing WCAG 1.4.11's 3:1 against its ring in **both** modes; **(3)** `isolate` added to the circle, since `relative` with `z-index: auto` creates no stacking context, so the contents' `z-10` escaped and painted over the sibling status dot.
+- **`Select` — `searchPlaceholder` was ignored** — The prop was declared and documented, but the search input hardcoded `"Search..."`, trapping a user-facing string (every built-in visible string must be overridable). It's now threaded through the Select context to the input. The default was inconsistent too — `SelectProps` documented `"Search..."` while the implementation defaulted to `"Search options..."`; both are `"Search..."` now. This is also what `InputAddress`'s new `showCountrySelector` depended on, since it was already passing `searchPlaceholder` to the country Select.
+- **`Message` — system bubble radius bypassed the surface cap** — It derived from a bare `calc()` on `--radius-base`. It's a tiny, tight-padding chip, so it now takes `--surface-radius-cap-xs`; without the cap, a theme chasing pill controls at a large base rounded the corners past what the bubble's own padding could absorb.
+- **`Metric` — `label` is now optional** — It was required with no reason to be; a metric can legitimately render a value alone. The generative schema is regenerated to match.
+- **Generative — `registry.tsx` was missing `"use client"`** — It renders JSX with a real event handler (Calendar's `render` wraps the underlying `onChange`) but carried no directive, a genuine gap under the RSC deep-import rule. Separately, the `audit-use-client` script's browser-global heuristic was flagging `schema.generated.ts` on the literal word "navigator" inside an unrelated description string; that file is pure JSON-shaped data and is now excluded from the audit rather than given a directive the generator would strip on the next run.
+- **Generative schema was stale for `InputOTP`** — The new `size` prop landed without a `yarn build:generative` regen, so the committed schema still advertised OTP without it and an LLM had no way to emit a sized OTP. Regenerated and committed as part of this release.
+- **`Calendar` — focus rings clipped by the height animation** — The days grid is inside a container animating height with `overflow: hidden`, which cropped the focus ring on edge cells. The grid is now padded so the ring clears. An unused `navButtonStyle` theme key was also removed.
+
+## [1.0.0-beta.30] - 2026-07-04
+
+### Breaking Changes
+
+- **`glass` variant removed** — `Alert`, `Toast`, and `Metric` no longer ship a `glass` variant. The `AlertVariant` / `ToastVariant` types (and the `variant` prop on `Alert`, `Toast`, `useToast` options, and `ToastData`) are removed entirely — `Alert` and `Toast` are now single-look components. `MetricVariant` drops `glass` (now `'filled' | 'ghost'`), and `MetricTheme`/`MetricThemeOverrides` drop `iconGlassShadows`. Migration: remove any `variant="glass"` / `variant="default"` props from these components; for a glass look compose `GlassEffect`/`GlassSurface` manually.
+- **`PageLayout` removed** — The `PageLayout` compound component (`PageLayout.Sidebar` / `.Header` / `.Content`) is removed from the library, barrel exports, docs, and the MCP registry. It was superseded by `AppShell` (beta.27), which covers the same full-viewport layout with region sub-components. Migration: replace `PageLayout` with `AppShell` (`Sidebar` → `AppShell.Sidebar`, `Header` → `AppShell.Header`, `Content` → `AppShell.Main`).
+- **`Button` — `link` variant removed** — `ButtonVariant` is now `'filled' | 'outline' | 'soft' | 'ghost'`. Use the `Link` component for text-action affordances. `Link` is now **polymorphic by behavior**: pass `href` to render an `<a>`, omit it (with `onClick`) to render a real `<button>` styled as a link, and it gains `color` (shared `SemanticColor`), `type`, `target`, and `rel`. `LinkProps` now extends `HTMLAttributes<HTMLElement>` (was `AnchorHTMLAttributes<HTMLAnchorElement>`).
+- **`Button` — `error` state removed** — `ButtonState` is now `'default' | 'disabled' | 'loading'`. Form errors belong on form controls via `state="invalid"` + `errorMessage`, not on the action button. The loading state was also reworked: loading now resolves *before* disabled so a loading button keeps its color instead of desaturating; the spinner uses `border-current` so it inherits the button's text color (the `-contrast` token on filled variants — no hardcoded white, so it stays visible under brand overrides and dark mode); the button emits `aria-busy` while loading and uses `cursor-wait`.
+- **`Button` — `color` narrowed to `'neutral' | 'primary' | 'danger'`** — `success`/`warning` removed from `ButtonColor` (they remain on the shared `SemanticColor` set for Badge/Alert/Toast/KPI/etc., which are status indicators, not actions). Migration: replace `color="success"`/`color="warning"` on `Button` with `color="primary"` (or `"danger"` if the action itself is destructive/negative). The generative schema was regenerated accordingly, so `Button` no longer offers `success`/`warning` there either.
+- **`InputAddress` / `InputCreditCard` — group-led invalid state** — Composite inputs now take a consolidated `state="invalid"` + `errorMessage` on the group (`aria-invalid`/`aria-errormessage` on the `<fieldset>`), painted as one red perimeter overlay around the stitched fields instead of reddening each field; the message renders once with `role="alert"` and self-clears on the next edit. Per-field `helperText` was stripped. `InputAddress` gains top-level `state`/`errorMessage`, and its `countryInputProps` changed type from `Omit<InputProps, 'ref'>` to `Partial<SelectProps<string>>` (the country field is a `Select` — pass `searchable`, `placement`, etc.). `InputCreditCard`'s `error` prop is deprecated in favor of `errorMessage` (kept as an alias for now). Interior 1px seams between fields no longer double up, and a focused field lifts its own ring above its neighbors.
+- **`StackedBarChart` — default `variant` is now `"gradient"`** — matches `BarChart`/`AreaChart` (premium per-segment gradient + lift shadow + hover glow). Pass `variant="default"` for the previous flat fills.
+- **`LineChart` — `secondary` removed from its `SemanticColor`** — the chart `color` prop type is now `'primary' | 'success' | 'warning' | 'danger'` (the `secondary` semantic was already removed library-wide; use `neutral`/an explicit color).
+- **Charts — multi-series legends render by default** — With the new shared legend (see Added), omitting `legend` resolves to `'bottom'` for multi-series `config` (previously these charts rendered no legend at all) and `'none'` for single-series. Pass `legend="none"` to keep legendless multi-series charts.
+- **Charts — legend internals replaced** — The unused Recharts-style `ChartLegendContent` component and `ChartLegendContentProps` type are no longer exported from `@flikk/ui/charts`, and `ChartLegendProps` changed shape (now `{ items: ChartLegendItem[]; className? }` — an already-resolved `{key, label, color}` list). `RadarChartThemeOverrides` drops its bespoke legend styling keys (`legendStyle`, `legendItemStyle`, `legendDotStyle`, `legendLabelStyle`) — legends are now styled once via the shared `chartTheme.legend`. The dead shared `BarRenderer` / `LineRenderer` renderers were removed (the Combo variants now live under `ComboChart` internals).
+- **`ActivityRings` — `variant` prop removed** — `variant` was declared on `ActivityRingsProps` but silently ignored (a ring chart has no variant concept), so it has been removed from the type entirely. Rendering is unchanged; migration is deleting the prop. Type-level break only. (#50)
+- **`Table` — `data`/`columns` now win over `children`** — Passing both the data-driven and compound APIs previously let `children` silently win; per the library-wide collection contract (`items`/`data` wins, with a dev warning), `data`/`columns` now take precedence. Output changes only for consumers who were passing both — pick one API. (#54)
+
+### Added
+
+- **Relative-elevation surface engine** — New `SurfaceProvider`, `useSurfaceLevel` / `useSurfaceElevation`, and `surfaceClasses` exported from the theme entry: surfaces read the rung they sit on and paint `substrate + offset` (clamped 1–8), so overlays lift *relative to their host* at runtime — anchored overlays (Dropdown, Popover, Select, Tooltip) lift `+2` over wherever they open; grounded overlays (Modal, Drawer, CommandPalette, Toast) paint a fixed rung. Override is first-class: `elevation` prop (re-bases children too) › `ground`/`lift={false}` › auto lift; `className` always wins for the element's own paint. See `docs/SURFACE_ELEVATION.md`.
+- **Effects — 18 in-house WebGL2 shader effects** — Ported from paper-design/shaders (Apache 2.0) and built in-house so every color prop stays CSS-variable/theme-aware: 10 generative backgrounds (`Dithering`, `GradientMesh`, `StaticGradientMesh`, `StaticRadialGradient`, `Metaballs`, `ColorPanels`, `SmokeRing`, `GodRays`, `GrainGradient`, `PulsingBorder`), 2 dual-mode shape effects (`LiquidMetal`, `GemSmoke`), and 6 image filters (`Water`, `ImageDithering`, `PaperTexture`, `FlutedGlass`, `HalftoneDots`, `HalftoneCmyk`). All exported from `@flikk/ui/effects`. Built on shared shader infrastructure (generalized from `AIOrb.Aura`): tab-visibility RAF pause, image-texture loading, and a `resolveShaderColor` that normalizes any CSS color syntax — including `oklch()` and `var(--…)` theme tokens.
+- **`MeshGradient`** — New effect in `@flikk/ui/effects`: a deterministic seed → marble-gradient tile (faithful SVG port of boring-avatars' marble — base rect + two Gaussian-blurred signature paths, transformed per seed; blur is in viewBox units so it's resolution-independent). Props: `seed`, `colors` (any CSS colors incl. theme vars), `blendMode`, `animated`, `noise` (grain overlay, default on). Also exports `MESH_PALETTES` / `MESH_PALETTE_BY_NAME` / `pickPalette` (curated palettes, `MeshPaletteName`) and `getMeshTextTone(seed)` — the readable text tone for a seed's gradient.
+- **`Shimmer`** — New effect in `@flikk/ui/effects`: CSS-only shimmer with two variants — `text` (the "AI thinking" text-clip highlight sweep) and `surface` (a highlight band sweeping across a loading placeholder box). Polymorphic `as` prop, `active` toggle (freeze without unmounting), `duration`/band-width controls; respects `prefers-reduced-motion`; tokens themeable with a dark-mode override.
+- **`Avatar` / `Badge` — mesh-gradient background** — `Avatar` gains a `gradient` prop (`boolean | string` seed) rendering a deterministic `MeshGradient` as its background layer — the image sits over it, initials overlay on top, with the initials color picked automatically from the gradient's luminance (via `getMeshTextTone`) so it stays legible on light and dark gradients alike. Plus palette controls: `gradientVariant` (curated `MeshPaletteName`) and `gradientColors` (raw CSS color override). `Badge`'s avatar slot gains the same `gradient` / `gradientVariant` / `gradientColors` for imageless person chips.
+- **`PulsingBorder` — px-first geometry, neon glow, sweep animation** — New px-based props that stay constant at any element size: `radius` and `borderWidth` (the size-relative `roundness`/`thickness` remain, with exported `pxToRoundness`/`pxToThickness` converters), `glow` (one-sided neon falloff radiating outward from the line, lit by the moving spots), `offset` (gap between the host edge and the line), and `lineOpacity` (an always-visible hairline tracing the full border, gradient-tinted through `colors`). New `animation="sweep"`: a single soft beam orbits the border at constant speed, its color gliding through the `colors` ramp each lap — the default `"pulse"` keeps the original flickering-spots look.
+- **Charts — `legend` prop + shared `ChartLegend`** — Every Cartesian chart (`AreaChart`, `BarChart`, `LineChart`, `StackedBarChart`, `ComboChart`) plus `ScatterPlot`/`RadarChart` now renders one shared, consistently-styled legend, controlled by `legend?: 'top' | 'bottom' | 'none'` on the standard chart props. Swatch colors come from each chart's own series-color resolver, so the legend always matches the plot. (Default behavior change — see Breaking Changes.)
+- **RSC / Next.js App Router support** — dist now ships a `"use client"` directive on every client module (via `rollup-plugin-preserve-directives` + preserved modules), so App Router consumers can import components directly in server files with no client wrapper re-exports. Server-safe modules (`.types.ts`, `.theme.ts`, pure utils/validators) deliberately stay unmarked so server components can import them with zero client JS; a new build-time audit (`scripts/audit-use-client.mjs`) fails the build if coverage drifts.
+- **`Grid` / `Stack` — polymorphic `as`** — Both accept `as?: LayoutTag` to swap the rendered `<div>` for a semantic tag (`ul`/`ol`/`nav`/`section`/`header`/`footer`/`aside`/`form`/`fieldset`) — e.g. a stack of nav links as `as="nav"`, a grid of cards announced as a list via `as="ul"`. Curated string union (not `React.ElementType`) so it stays JSON-serializable for the generative-UI schema.
+- **`Accordion` — `items` data API + disabled items** — Accepts a serializable `items?: AccordionItemData[]` (`{ value, title, content?, className? }`) alongside the compound API, rendering through the same `Accordion.Item`/`Trigger`/`Body` primitives (one render path); `items` wins over `children` with a dev warning. Joins the sanctioned Dual-API set (Table, Timeline, DescriptionList, Feed). `Accordion.Item` also accepts `disabled`: the trigger renders natively disabled and roving arrow-key navigation skips it.
+- **`PageHeading` — slot-props** — Accepts flat `title` / `subtitle` / `actions` slot-props composing the real `Title`/`Subtitle`/`Actions` sub-parts (managed mode), alongside the unchanged compound API — mirrors `Card`/`Section`.
+- **Generative UI — curated set 22 → 30** — Eight components join the generative registry/schema: collections `Breadcrumbs`, `AvatarGroup`, `Accordion`, plus leaves `Empty`, `Rating`, `Pill`, `Tag`, and `PageHeading` (slot-prop header). Schema, tool def, and runtime `defaultRegistry` regenerated in the same pass.
+- **`ContextMenu` — `startContent` slot** — `ContextMenu.Item` and `SubTrigger` gain a `startContent` leading-icon slot rendered in its own flex slot. The checked tick of checkable items now occupies the same leading gutter (with a spacer when unchecked), so checkable rows align with icon rows and labels never shift on toggle; `aria-checked`/`data-checked` are only emitted for actually-checkable items.
+- **Forms — `errorMessage` on the whole family** — `Input`, `Textarea`, `InputDate`, `InputOTP`, `InputCounter`, `DateRangePicker`, `ColorPicker`, `RichTextEditor`, and `Signature` gain `errorMessage?: ReactNode`, completing the standard form error pattern. It takes precedence over `helperText` in the invalid state and is wired to `aria-describedby`/`aria-invalid` with `role="alert"` on the message; `helperText` behavior is unchanged when absent. (#52)
+- **Forms — mask/validate split for expiry dates** — `formatExpiryDate` now clamps the month as you type (component owns format only); business validity stays the consumer's via new exported pure validators `isValidExpiryDate` / `isValidMonth`. `inputTheme` is also re-exported from the forms barrel.
+- **`Calendar` — full keyboard grid navigation** — Roving tabindex plus arrow-key day navigation per the APG grid pattern. (#53)
+- **`colorUtils` — contrast helpers** — New pure, dependency-free helpers: `hexToRgb`, `relativeLuminance` (WCAG), and `contrastTone(bg, { threshold })` → `"light" | "dark"` — picks the higher-contrast text tone for a background (accepts an array of colors and averages luminance, for gradients; `threshold` defaults to the WCAG 0.179 black/white crossover).
+- **Automated test infrastructure** — Vitest 3 + React Testing Library + jest-axe on jsdom, with `yarn test` / `yarn test:watch`, shared `renderWithProviders` test utils, ResizeObserver/matchMedia polyfills, and the library's first CI workflow (typecheck, lint, test, build on every push/PR); `prepublishOnly` now runs the suite. (#39)
+- **Library-wide test backfill** — ~2,200 tests across ~155 co-located `*.test.tsx` files covering every component category (forms, overlays, core interactive, display + data-display, charts, AI + layout, effects, NodeCanvas, generative engine) at WAI-ARIA APG depth: full keyboard matrices, controlled/uncontrolled parity with exact `onChange` payloads, resolved `aria-describedby`/`aria-errormessage` contracts, and jest-axe across states. The backfill pinned every defect fixed below; the full suite is deterministic under parallel runs (three.js-backed suites isolated into a sequential Vitest project). (#40–#48, #54)
+
+### Changed
+
+- **Theme polish pass** — Toast, Pill, Badge, Radio, and related themes migrated to the shared surface/interaction tokens (`--color-surface*`, `--color-surface-hover`, `--color-border-hover`, `shadow-real-*`) and off bespoke per-step neutrals and the deprecated `--color-background-secondary` / `secondary` colors. Badge `soft`/`filled` now keep a transparent 1px border (consistent height); semantic fills drive from the mode-aware base var so auto-derived `-contrast` text stays readable. `FunnelChart` reworked visually (gradient fills, soft `Badge` callouts). Chart animation timings consolidated into `charts/utils/animation-utils.ts`.
+- **Outline borders — full-color, library-wide** — `outline` variant borders are now color-matched per semantic color: `neutral` → `--color-border-secondary` (hueless, full-weight — no longer the faint `--color-border` hairline); `primary`/`success`/`warning`/`danger` → `border-[var(--color-{color}-600)]` (+ `-400` in dark), matching the text. Applies to `Button` (neutral only changed) and `Badge` (all five colors). Visual diff for outline Badges/Buttons.
+- **Forms — invalid-state visual unified** — Invalid now paints a danger border + faint danger ring with **no surface fill** (previously a danger-50 background tint) — one treatment across single fields, OTP slots, and the new composite-group perimeter overlay.
+- **`PulsingBorder` — self-configuring fit (visual behavior change)** — With no sizing props, the corner radius now auto-matches the host element's computed CSS `border-radius` (previously a fixed `roundness` of `0.4`), and the border line now sits fully *outside* the host (inner edge touching) so it never overlaps card content. The wrapper auto-expands past the host by exactly the room the soft band/glow needs, so the halo always fades out instead of cropping at the host edge. Existing usages will render slightly differently by default; pass explicit `roundness` and `margin` to approximate the old inside-the-box look.
+- **Circular dependencies eliminated library-wide** — All 34 module cycles across 10 compound-component families (Accordion, Modal, Drawer, Animated, Table, Timeline, GanttChart, DatePicker, DateRangePicker, TimePicker) are gone: contexts extracted to dedicated `[Name]Context.ts` modules with the root files re-exporting the moved names, so public import paths are unchanged. Consumers' bundlers no longer emit circular-dependency warnings for `@flikk/ui`.
+- **`NodeCanvas` — render-performance contract documented** — The split-context memoization (per-frame state vs. stable API contexts, memoized node/edge renderers: a graph update re-renders only the changed node; pan/zoom re-renders none) is now documented in `docs/NODE_CANVAS.md` — keep your `nodeTypes` map referentially stable or the memoization is defeated. The `NodeCanvasEditorLayout` reference story was reworked to demonstrate it.
+- **`Segmented` — `data-state` attribute** — Items now emit `data-state="active|inactive"` alongside the existing `data-selected`, matching the library-wide `data-[state=*]` styling convention. `data-selected` is kept for one deprecation cycle. (#54)
+- **`Tag` — spacing polish** — Tighter remove-button hit area, balanced avatar/icon left inset, and adjusted `md` padding.
+
+### Fixed
+
+- **Charts — rules-of-hooks crashes** — `AreaChart`, `LineChart`, `StackedBarChart`, and `ActivityRings` threw "Rendered more/fewer hooks than during the previous render" when their data transitioned between empty and populated (early returns sat mid-hook-sequence); a follow-up sweep fixed the remaining conditional-hook sites in `Table`'s filter row and `Sidebar` navigation. (#50)
+- **Charts — empty data no longer renders as an error** — `BarChart`, `StackedBarChart`, and `ComboChart` misclassified `data={[]}` as invalid and showed the red "Invalid Chart Data" panel; empty data now reaches the proper empty state. Genuinely invalid (non-numeric) data still errors. (#50)
+- **`Heatmap` — standalone crash + grid semantics** — No longer throws when used with directly-passed `data`/`config` outside a chart container (its documented contract). Also emits a valid `grid > row > gridcell` structure for assistive tech with no visual change. (#50, #54)
+- **`ComboChart` — `variant` now applied** — The declared `variant` prop was silently dropped; it now threads through to the bar renderer (line glow remains always-on, matching `LineChart`). (#50)
+- **`Combobox` — opening no longer filters by the selected label** — With a value selected, opening the listbox previously narrowed it to the single already-selected match (the selected label doubles as the input text). The list now stays full on open and only filters once the user actually types, matching `Select` and the WAI-ARIA editable-combobox pattern.
+- **`Checkbox` / `Radio` — rest props reach the `<input>`** — `aria-label` and other rest props were spread onto the wrapper `<div>`, leaving the actual control unlabeled (this surfaced in `Table`'s row-select checkboxes). Rest props now land on the `<input>`; `className` stays on the wrapper. (#51)
+- **`Toast` — per-toast live regions** — Only the container had `aria-live`; each toast now carries `role="alert"` (danger/warning) or `role="status"` (info/success) so screen readers announce exactly once, with per-toast urgency. (#51)
+- **`Toast` — timer resume** — Hovering or expanding a toast now resumes the *remaining* auto-dismiss time instead of restarting the full countdown on every hover/expand toggle.
+- **A11y — labels on roleless elements** — `Avatar` now actually renders its computed `role` (fallback-initials avatars and consumer `role="img"` are honored); `SlidingNumber` gets `role="img"`; `Message`'s status indicator moves its label to an sr-only text node with the glyph `aria-hidden`. (#51)
+- **`InputTag` — paste and reopen bugs** — Pasting comma-separated values committed only the last tag (stale-closure loop); all values now commit in one update, respecting `maxTags` and dedup. The suggestion dropdown also no longer reopens immediately after a click selection. (#52)
+- **`DateRangePicker` — controlled mode drift** — Internal state no longer updates when a `value` prop is provided; `onChange` always fires. (#52)
+- **`Signature` — `onChange` while disabled** — Pointer-up no longer fires `onChange` on a disabled signature pad. (#52)
+- **Date formatting — March/May mangled** — `formatDateCustom` ran sequential replaces that re-matched the "M" inside already-substituted month names ("Mar" → "3ar"); formatting is now a single tokenized pass. Affects date display across the date/time inputs. (#52)
+- **Forms — combobox roles and names** — `TimePicker`, `ColorPicker`, `InputTag` (with suggestions), and `Mention` triggers get proper `role="combobox"` + `aria-controls`; `InputOTP` slots get indexed labels ("Digit N of M"); `Slider` sets `aria-invalid`; `Pill` no longer dev-warns on every selectable-less pill. (#52)
+- **`Checkbox` — standalone invalid** — A standalone invalid checkbox now emits `aria-invalid`.
+- **Nested overlays — six more overlays join the portal guard** — `TimePicker`, `DatePicker`, `DateRangePicker`, `Mention`, `InputTag`, and `RichTextEditor` portals now carry `data-flikkui-portal`, so picking a value inside one of them no longer dismisses an ancestor overlay (Popover/Modal/Drawer).
+- **`Dropdown` — nested overlay dismissal** — Picking an option in a portaled `Select` inside a `Dropdown` menu no longer dismisses the menu (the `data-flikkui-portal` click-outside bail was missing). (#53)
+- **Overlay a11y** — `ModalStack` drops a redundant unlabelled `role="dialog"` wrapper; `AlertDialog`'s subtitle renders through `Modal.Subtitle` so `aria-describedby` resolves; `Tooltip` puts `aria-describedby` on the trigger element itself (via `useId()`), not a wrapper; `CommandPalette` keeps group labels for grouped input and skips disabled rows in arrow navigation; `ContextMenu` uses `role="menuitemcheckbox"` when checked and returns focus to the trigger on close. (#53)
+- **`Select` — keyboard open + focus return** — Opens on ArrowDown/ArrowUp while closed, restores focus to the trigger after mouse selection, and the listbox gets an accessible name. (#53)
+- **`Button` — consumer `data-state` honored** — A consumer-passed `data-state` is no longer clobbered by the internal one (fixes active/inactive toolbar buttons, e.g. in `RichTextEditor`). (#53)
+- **Navigation a11y sweep** — `Tabs` arrow navigation skips disabled triggers; `Sidebar`/`NavItem` active items get `aria-current="page"` and submenu `aria-expanded` is no longer clobbered; `Breadcrumbs` marks only the current crumb `aria-current`; `Pagination` clamps disabled Prev/Next labels at bounds; `Carousel` passes `inert` as a real boolean (React 19 — it previously never applied); `MenuItem` sets `aria-selected`/`aria-checked` per role; `Tree` adds `role="group"` on child lists and hides chevrons from treeitem names; `Rating` removes nested-interactive star buttons inside its `role="slider"`. (#53)
+- **`DragDrop` — keyboard drops** — Keyboard drop fired `onDrop` twice and arrow-cycling could only reach the first zone; drops now fire once with a full `type`/`data` payload and cycling reaches every zone. (#53)
+- **`NodeCanvas` — pointer-capture crash** — Pane `setPointerCapture` is guarded, so panning no longer throws in environments without pointer-capture support. (#53)
+- **`Message` — typewriter `onComplete` timing** — The typewriter's `onComplete` now fires after the animation actually settles, and also fires on the reduced-motion/disabled path (it previously fired at first paint, or never). Internal render is now pure (no ref mutation during render).
+- **`Input` — nested trigger ring bleed** — A nested `aria-haspopup` trigger inside an Input addon (e.g. an embedded `Select`) no longer renders its own hover/focus edge and ring over the host field.
+- **`CodeBlock` — `highlightLines` / `diffMode` without line numbers** — Both silently no-oped unless `showLineNumbers` was on; they now work independently. (#54)
+- **`ImagePlaceholder`** — The `rounded` prop was a no-op (read the wrong CSS variable) and `ratio={undefined}` (fill-parent escape hatch) was dead code; both work now, and the default 16:9 still applies when `ratio` is omitted. (#54)
+- **`useNetworkStatus` — initial offline state** — Seeds from `navigator.onLine` (SSR-safe), so a page loaded offline reports offline immediately instead of after the first event. (#54)
+- **`Table` — header semantics** — Header cells get `scope="col"` and sortable data-driven headers wire `aria-sort`. (#54)
+- **`PulsingBorder` — glow rendered at true strength** — The shader emitted premultiplied alpha while `ShaderCanvas` composites straight alpha, so every soft pixel rendered at alpha² and the glow was effectively invisible; output is now un-premultiplied. Also: the host is measured via layout px (`offsetWidth`/`offsetHeight`), so the ring no longer drifts off its card under ancestor `scale()` transforms such as `NodeCanvas` zoom.
+- **`ColorPicker` — gradient detection** — `isGradientString` now matches `repeating-*` gradients.
+- **`Masonry` — relayout thrash** — Pre-paint relayout is keyed on child count rather than children identity, avoiding a synchronous measure-and-arrange on every render.
+- **`PromptInput` — paused waveform** — The voice recorder skips waveform redraws while paused (battery).
+- **`TimePicker` — footer sizing** — Restored the footer Cancel/Save `flex-1` sizing.
+- **`PromptSuggestion` — restored to the MCP registry** — Its folder (`ai/PromptSuggestions/`) was renamed to match the component name, so it is discovered by the inventory generator again (it was silently missing from `registry.json`).
+- **Effects hygiene** — `GlassSurface` uses the shared `useDarkMode` singleton; `GlassEffect` and `AIOrb.Aura` are `aria-hidden` decorative (Aura also gains an SSR client gate); `OfflineIndicator` drops a hardcoded `text-white`; `InputCounter`'s decorative gesture wrappers no longer add unlabeled tab stops. (#54)
+- **Generative — `Badge` schema default** — The generated schema declared `"default"` as `Badge`'s color default, which isn't in its own enum; corrected to `"primary"` (the real runtime default) and regenerated. (#49)
+
+### Security
+
+- **Generative — `validate()` boundary hardened (7 fixes)** — The generative-spec validator was adversarially tested and hardened; specs from untrusted LLM output are now safe against a class of prototype/injection attacks: (#49)
+  1. Component names colliding with `Object.prototype` keys (`"constructor"`, `"__proto__"`, `"toString"`, …) no longer crash `validate()` — every dynamic map read is gated on `Object.hasOwn`, restoring the "never throws" contract (unknown names take the normal unknown-component path).
+  2. `constructor`/`__proto__` prop keys record an unknown-prop issue instead of silently vanishing.
+  3. Object-shaped structured props (`chartConfig`, `donutColors`, `gridCols`, and every array-of-object shape) are now recursively sanitized — nested `className`/`style`/`dangerouslySetInnerHTML`/`on*` handlers/functions previously bypassed the injection guard entirely; each strip is a recorded issue.
+  4. Handler detection is case-insensitive — `onclick`/`ONLOAD` are blocked, including via custom schemas.
+  5. `actions.*.payload` runs through the same sanitizer (was copied verbatim).
+  6. Recursion is depth-limited (100) at both node and structured-value levels — pathologically deep specs prune with a recorded issue instead of overflowing the stack.
+  7. Prototype-pollution write-key guard: `__proto__`/`constructor`/`prototype` are denied at both dynamic-write sites, closing a silent prototype-chain hijack the read-side guard didn't cover.
+
+### MCP server (`@flikk/mcp`)
+
+- New `customize_theme` tool (topic-filterable guide to overriding the Flikkui theme — brand palettes, radius, fonts, dark mode, `generatePalette`/`generateThemeCSS`); new self-describing `manifest` tool introspecting every tool's args/types/defaults/error codes; `get_component`/`get_block` not-found paths now return a stable, parseable `{error: {code, message}}` contract; new `review_usage` rule `overlay-portal-false-in-popover`.
+- New `get_changelog` tool — per-version release notes with `since` (everything newer than a given version), `version`, and `breaking_only` filters, so an agent can read the breaking changes + migration paths after an `@flikk/ui` upgrade and fix code against them. Reads the changelog of the installed `@flikk/ui` when present (falls back to a bundled snapshot); to support that, **`@flikk/ui` now ships `CHANGELOG.md`** in the npm package (exported as `@flikk/ui/CHANGELOG.md`).
+
+## [1.0.0-beta.29] - 2026-06-16
+
+### Breaking Changes
+
+- **Effects removed** — `Glass`, `MorphingText`, `ParallaxSection`, `Spotlight`, `StickyScroll`, and `SpotlightBorder` are no longer exported from `@flikk/ui/effects`. `Glass` (the refraction "lens" effect) was added in beta.28 and is removed here — use the mix-blend-mode `GlassEffect` (or `GlassSurface`) instead. (PER-160)
+- **`PageTransition` → `Preloader`** — The `PageTransition` effect was renamed to `Preloader` (component, types, stories, docs, and registry entry). Update imports: `import { Preloader } from "@flikk/ui/effects"`. The animation engine was reworked with creative reveal variants (blinds / shutters / layers / iris).
+
+### Added
+
+- **`HeroCard`** — New core component: a media/hero card with a parallax tilt surface (`parallaxIntensity`, default `32`). Exported from `@flikk/ui/core` (and the main barrel). (PER-160)
+- **`TiltCard`** — New effect component: 3D pointer-tilt card. Tilt is CSS-only; the `glow` layer lazy-loads `three`. Exported from `@flikk/ui/effects`. (PER-160)
+- **`ScrollArea` — drag-to-scroll** — Pointer drag-to-scroll backed by the smooth-scroll engine, with momentum. (PER-160)
+- **Charts — `width` / `height` props** — Cartesian charts (`AreaChart`, `BarChart`, `LineChart`, `StackedBarChart`, `ScatterPlot`) accept explicit `width`/`height`, and `config.color` now resolves Tailwind palette names (e.g. `"blue-500"`) in addition to CSS variables/hex. (PER-161)
+
+### Changed
+
+- **Theme — elevation polish pass** — Re-tuned the surface/elevation ladder to read *lighter in both modes* (monotonic + symmetric: higher = lighter), with real dark-mode-aware `shadow-real-*` / `shadow-inner-real-*` shadows (`--elevation-*` tokens; `.dark` swaps to a stronger depth-pool + a 1px white top rim). Refined the `AppShell` color model — only `root` paints the floor; chrome inherits; side-by-side panels are opt-in; horizontal sticky bars use a translucent frosted-floor tint. (PER-163)
+- **`ProgressiveBlur` — perf + a11y** — Dropped redundant per-layer `z-index` (the `backdrop-filter` already establishes a stacking context), `aria-hidden` on decorative instances, memoized layer style objects, clamped/guarded the `layers` prop, deduped position arrays, and dev-warns on `ref` + multi-position. Demo wrappers constrained so the blur no longer smears past the container edge. (PER-164)
+- **Assets** — `public/bg` backdrops converted from JPG to WebP for smaller payloads. (PER-162)
+
+### Fixed
+
+- **Charts — `ScatterPlot` tooltip** — Fixed the tooltip rendering/positioning on `ScatterPlot`; tidied its theme and types. (PER-161)
+
+### Removed
+
+- **Story-only blocks** — `ChangelogLayout` and `WaitlistLayout` reference layouts were removed (story-only, never part of the public API).
+
+## [1.0.0-beta.28] - 2026-06-11
+
+### Breaking Changes
+
+- **`Card`** — The `title` prop is now a **header slot** (`ReactNode`), not the native DOM `title` attribute. `CardProps` changed from `extends HTMLAttributes<HTMLDivElement>` to `extends Omit<HTMLAttributes, "title">`. Passing `title="…"` to a `<Card>` for a hover tooltip now renders a card header instead. Migration: move tooltip text to a wrapper element, or compose `Card.Header` explicitly. (PER-148)
+- **`BarChart` / `AreaChart`** — Default `variant` changed from flat `"default"` to `"gradient"` (the premium look). Charts render with gradient fills/glow unless you pass `variant="default"`. Also: `showDots` default `true → false` and `dotRadius` default `4 → 3`. (PER-149)
+- **`Metric`** — The `MetricTheme` / `MetricThemeOverrides` shape was fully restructured to a flat per-element form. Removed `variantColors`, `iconContainerVariantColors`, and the nested `sizes` record; added flat records (`iconContainerVariants`, `iconColors`, `iconGlassShadows`, `contentPaddingSizes`, `iconContainerSizes`, `labelSizes`, `valueSizes`, `subtitleSizes`). Consumers passing a custom `theme` to `<Metric>` must migrate. (PER-155)
+- **Theme — surface recolor** — The surface/elevation ladder values were re-tuned (`src/styles/theme.css`): light mode now uses a pure-white page/overlay with a neutral-100 card fill; dark mode uses a near-black floor with faintly cool ascending surfaces. Visual diff for all consumers. The legacy `--color-background-secondary…quinary` tokens remain deprecated aliases (removal in the next major). (PER-132)
+
+### Added
+
+- **Generative UI engine** — New `@flikk/ui/generative` subpath: spec-renderable FlikkUI. An LLM emits a serializable `UINode` JSON tree that the engine validates and renders. Includes `GenerativeView`, `createRegistry`/`defaultRegistry`, `validate` (zero-dep repair), streaming (`parseStreamingSpec` + `useGenerativeStream`), serializable actions (`onAction`), and a runtime tool-def export (`GENERATIVE_TOOL` / `buildToolDefinition`). Curated, schema-checked 22-component safe set; one generation pass emits `schema.generated.ts` + `dist/generative.schema.json` + `dist/tools.json` (cannot drift). Subpath-only (not in the main barrel). See `docs/generative-ui.md` and CLAUDE.md §22. (PER-136, PER-138–142)
+- **Layout primitives** — `Grid`, `Stack`, `Section` exported from `@flikk/ui/layout` (and the main barrel). `Grid` `cols` is a mobile-first auto-ramp number or explicit per-breakpoint map (purge-safe literals); `Stack` is the flex counterpart; `Section` is a titled region wiring `aria-labelledby`. (PER-137)
+- **`items` data API** — Collection components `Table`, `Timeline`, `DescriptionList`, and `Feed` now accept a serializable `items` array alongside their compound API (one render path), so they drop into a generative-UI registry with no bespoke renderer glue. `Feed` also gains `collapseAfter`. (PER-133)
+- **`Card` slot-props** — `Card` accepts flat `title` / `subtitle` / `actions` / `footer` slot-props alongside the compound API (mirrors `Section`). Setting any slot switches the card to managed mode (auto `Header`/`Body`/`Footer`); setting none renders children raw. (PER-148)
+- **`Glass`** — New refraction "lens" effect in `@flikk/ui/effects` (`Glass`, `GlassLens`, `GlassProps`). Bends the live DOM it sits over (or an optional `refractionTarget`) via an SVG displacement filter — lens geometry, x/y travel, strength, erf-falloff depth band, spherical-dome profile. Distinct from the mix-blend-mode `GlassEffect`. (PER-147)
+- **`Metric`** — New `ghost` variant. (PER-155)
+- **`Table`** — `onRowClick(row)` on the data-driven API; rows get pointer cursor + keyboard activation (selection/expand controls still `stopPropagation`). (PER-141)
+- **Charts — `useChartDimensions`** — New shared hook (`charts/hooks`) for layout-effect container measurement with a `measured` gate. (PER-149)
+- **Canvas** — `Handle` accepts `children` for custom port visuals; `edge.color` per-edge stroke override. (PER-143)
+- **Blocks** — New story-only reference layouts: `LMSDashboardLayout` (PER-153), interactive range-chart `GenerativeUI` cards + schema inspector (PER-154), and a Generative UI social-profile block (PER-135).
+
+### Changed
+
+- **Charts — shared `X_AXIS_MARGIN`** — The X-axis bottom margin is now a single shared constant across Area/Line/Bar/StackedBar so plot baselines align when charts sit side by side. (PER-134)
+- **`CanvasToolbar`** — The node palette collapsed into a single "+ Add node" dropdown of `nodeOptions`. (PER-144)
+- **Theme polish** — Visual refinement across `Badge`, `Button`, `PageHeading`, `Tooltip`, `Table`, `Card`, and `Metric` (label/icon alignment, value sizing, soft-variant tints, header typography, backdrop blur). (PER-151, PER-152)
+- **Canvas** — Quieter `BaseNode` selection (border-secondary + ring-2 primary whisper); real pane background with a visible dot grid. (PER-143)
+
+### Fixed
+
+- **Charts — cold-load dimension race** — Charts measured their container in a 600×400 fallback before the real size landed, so mount animations captured the wrong transform-origins (bars rose from below the x-axis, clip-sweep reveals froze short, dots flew in from wrong spots). `useChartDimensions` now measures via a layout effect and exposes a `measured` flag that gates mount-animated SVG geometry. (PER-149)
+- **`shadow-real-*` utilities** — Re-registered as Tailwind `@utility` rules instead of hand-written `@layer utilities` classes, so variant prefixes (`hover:`, `group-hover:`, `dark:`, …) now generate. Previously the base class worked but its variants were silently dropped. (PER-150)
+- **`Dropdown`** — Placement-aware menu animation, a working keyboard layer, and Escape-to-close. (PER-145)
+- **`Grid` / `Section`** — Grid auto-ramp is monotonic and extends to `xl` for high column counts; `Section` wires the `aria-labelledby` landmark and skips an empty body. (PER-137)
+
+## [1.0.0-beta.27] - 2026-05-29
+
+### Added
+
+- **`AppShell`** — New layout component exported from `@flikk/ui/layout`. Provides a full viewport shell with region-named sub-components: `AppShell.Topbar`, `AppShell.Sidebar`, `AppShell.Header`, `AppShell.Main`, `AppShell.RightPanel`, and `AppShell.Footer`. Context-driven scroll mode (`scroll="main"` | `"page"`) with support for full-height rails (Sidebar, RightPanel). Children-discovery layout algorithm auto-places regions without requiring explicit ordering. Includes Storybook stories covering Default (Operating Snapshot dashboard) plus Sidebar, RightPanel, Footer, and PageFlow variants.
+- **`Sidebar.Search`** — New `<Sidebar.Search />` sub-component (PER-67). Full-width search field that collapses gracefully in the rail state with a NavItem-style collapse animation, stable height on collapse, and a neutral icon with muted clear-x.
+- **`Sidebar.Card`** — New `<Sidebar.Card />` sub-component for surfacing a custom card slot in the sidebar; ships with a NavItem-as-row recipe for composing card content.
+
+### Changed
+
+- **`Sidebar`** — `children` and `Sidebar.Search` are now optional. Sidebar renders correctly with no child content (bare rail). This relaxes the previous hard requirement for children and enables minimal sidebar configurations.
+- **`Sidebar`** — Collapsed rail redesigned with uniform 36×36 hit-areas on a 60px rail for all interactive row elements (NavItem, Sidebar.Search, Sidebar.UserProfile). Sidebar.Search row width aligned with NavItem rows.
+- **`Popover`** — Viewport clamping, nested-overlay click-outside isolation, and auto-scroll support. A `Select` or `Dropdown` inside a `Popover` no longer inadvertently closes the ancestor when the user clicks an option. The popover now horizontal-clamps to stay on-screen near viewport edges and scrolls with its anchor trigger.
+- **`MediaGalleryLayout`** — Storybook story content refresh.
+
+### Fixed
+
+- **`Mention`** — Prevented a React `removeChild` crash that occurred when deleting a chip in a contentEditable host. Chips are now dismissable without causing a React reconciliation mismatch.
+- **`Tag`** — Balanced avatar/icon insets for leading-content tags; padding was asymmetric when a leading avatar or icon was present.
+- **Form controls`** — Hover-edge border added to form controls; `DotSeparator` menu updates.
+- **`NavItem`** — Fixed a type error that broke consumer builds compiling from source against `react@canary` types (e.g. Next 16). `NavItemProps extends HTMLAttributes<HTMLElement>` typed `onSubmit` as `SubmitEventHandler<HTMLElement>`, which is not assignable to `motion.a`'s element-specific `HTMLMotionProps<"a">` once `SubmitEvent` gains a type-parameter-dependent field. `onSubmit`/`onSubmitCapture` are now stripped before the spread (behaviour-neutral — a nav item never submits a form), alongside the existing drag/animation handler strips.
+
+## [1.0.0-beta.26] - 2026-05-22
+
+### Breaking Changes
+
+- **`Sidebar`** — Removed the `SidebarSubmenu` component. The Sidebar was rebuilt around context selectors, and nested navigation is now driven by `NavItem`'s `items` prop (with a collapsed-rail flyout) rather than a dedicated submenu component. Consumers using `Sidebar.Submenu` must migrate to `NavItem items={…}`.
+- **`NavItem`** — Removed the `isDanger` prop (and `dangerStyle` from the theme). Danger actions belong in a menu (e.g. `Dropdown.Item isDanger` inside `Sidebar.UserProfile`'s `dropdownContent`). The NavItem variant/theme/type surface was also reworked.
+
+### Added
+
+- **Theme — surface elevation ladder** — New semantic surface tokens `--color-surface-sunken`, `--color-surface-raised`, `--color-surface-overlay` (joining `--color-surface` and `--color-background`), plus the translucent `--color-surface-hover` interaction fill that composites over any surface level. Replaces the numbered `--color-background-secondary…quinary` scheme (kept as deprecated aliases for one major). See CLAUDE.md §3.
+- **`StripePattern`**, **`ImagePlaceholder`** — New components for empty image/banner slots.
+- **`Sidebar`** — Collapsed-rail hover **flyout submenus** (via `Dropdown`); `Sidebar.UserProfile` gains a `dropdownContent` menu and a custom `children` slot for the text region; new `UserMenu` story.
+- **`RichTextEditor`** — Expanded editing capabilities and theme.
+
+### Changed
+
+- **Theme migration onto the surface ladder** — Track/inset fills → `surface-sunken`; row/item/button hovers → `surface-hover`; overlays (Dropdown, Popover, Tooltip, etc.) → `surface-raised`/`-overlay`; chart null/dimmed fills → `surface-sunken`. No new usage of the legacy `background-*` tokens.
+- **`NavItem`** — Two-line expanded layout (title + accessories, optional description); collapsed notifications render as a dot with an sr-only unread count; smoother padding/gap transitions.
+- **`FileUploadProgress`** — Separated retry vs. remove behavior; the radial now doubles as the cancel/remove target with a shared confirm popover; larger radial center text.
+- **`InteractiveCharacters`** — Redesigned the blob/tall/small character SVGs.
+- **`KPI`** — Bumped label + subtitle typography contrast.
+- **`Table`** — Added `flush` edge padding; trimmed block templates.
+- **`MorphingText`** — Cross-fade now animates between measured text sizes.
+- **Docs** — Condensed CLAUDE.md reference guide; README updates.
+
+### Fixed
+
+- **Form-control borders** — Resting + focus borders on every form control (Input, Select, Combobox, Date/Time pickers, Textarea, etc.) are now drawn with an inset `box-shadow` instead of `outline`/`border`. Clip-safe inside `overflow-hidden` parents, no focus reflow, and the same height as `Button`. (Fixes the input-clip and Select-vs-Button size mismatch — Linear PER-58, PER-61.)
+- **`ScrollArea`** — The `type="scroll"` overlay thumb was hardcoded `black/30` (invisible in dark mode); it now uses the mode-aware `--color-border`, and the `always` track moved off the deprecated `--color-background-secondary` onto `--color-surface-sunken`. (Linear PER-59.)
+- **`MorphingText`** — Fixed the inline-box width snapping during transitions by measuring all candidate strings; added an SSR-safe layout-effect shim.
+
+### Tooling
+
+- **`@flikk/mcp` 0.2.10** — Refreshed the component registry: 121 components (was 119), surface-ladder + text-taxonomy tokens, and removed stale `background-tertiary`/`background-quaternary` references.
+
+## [1.0.0-beta.25] - 2026-04-20
+
+### Breaking Changes
+
+- **`Timeline`** — Removed `align` prop and `TimelineAlign` type (`"left" | "right" | "alternate"`). Timeline now uses a single layout per the component's `layout` prop (`"vertical" | "horizontal"`). Consumers setting `align` must remove it.
+- **`Timeline.animations.ts`** — Internal animations module deleted. Not part of the public API, but anyone importing it directly will need to remove the reference.
+
+### Added
+
+- **`@flikk/ui/effects` barrel** — `AIOrb` (+ `AIOrbProps`, `OrbState`, `DotSphereProps`, `LiquidProps`, `AuraProps`), `Particles` (+ `ParticlesProps`), and `SpotlightBorder` (+ `SpotlightBorderProps`, `SpotlightBorderVariation`) are now exported from the effects barrel. Previously only reachable via their component subpaths.
+
+### Changed
+
+- **`Accordion`** — Trigger and body now inherit the library-wide `text-sm` baseline (was browser default).
+- **`Breadcrumbs`** — Link and current-page styles moved to `text-sm` for consistency with the library baseline.
+- **`Calendar`** — Dropped the `text-base` override on month/year `Select` dropdowns; they now use `Select`'s `size="sm"` default, matching every other Select in the library.
+- **`CalendarMini`** — Internal refactor pass (~850-line diff); no behavioural change.
+- **`Timeline`** / **`TimelineItem`** / **`TimelineContent`** — Simplified after removing the `align` prop and animation module.
+- **`Empty`**, **`Link`** — Minor theme and formatting cleanup.
+- **`Select`** — Removed an unused tag-class path on `Select.Tag`.
+
+### Fixed
+
+- **Stories — `docs.source.code` import paths** — Normalized across `Feed`, `GanttChart`, `DateRangePicker`, `TimePicker`, `AlertDialog`, and others so the Storybook "Show code" panel displays the public barrel entry (`@flikk/ui`) instead of internal paths.
+- **Story coverage** — Added `docs.source.code` to 14 previously missing stories and added new `MenuItem` stories. MCP code-example coverage is now 119/119 components.
+- **Timeline stories** — Added `text-sm` to `h4` headings so the preview matches the library-wide baseline.
+
+## [1.0.0-beta.24] - 2026-04-20
+
+### Breaking Changes
+
+- **`Segmented`** — Changed from `tablist`/`tab` ARIA roles to `radiogroup`/`radio` with roving `tabIndex` and arrow-key navigation. Consumers relying on the previous tab semantics must update keyboard interaction expectations.
+- **`DragDrop`** — Added required `aria-label` type prop for accessible list labelling. Existing usages without this prop will need to be updated.
+- **`CheckboxGroup` / `RadioGroup` `error` prop deprecated** — Use `state="invalid"` + `errorMessage` instead. The `error` prop will be removed in a future release.
+- **`label` / `helperText` props changed from `string` to `ReactNode`** across all affected form components (`Checkbox`, `Radio`, `Input`, `Textarea`, `Select`, `Combobox`, `Slider`, `DatePicker`, `DateRangePicker`, `TimePicker`, `FileUpload`, `InputOTP`, `InputCounter`, `CronInput`, `Mention`).
+- **`Checkbox` / `Radio`** now extend `InputHTMLAttributes` instead of `HTMLAttributes`. Prop forwarding behaviour may differ for consumers passing arbitrary HTML attributes.
+- **`InputCreditCard` / `InputAddress`** — Replaced `FormLabel` with `<legend>` inside `<fieldset>` for correct semantics. Visual appearance is unchanged but DOM structure differs.
+- **Main barrel (`@flikk/ui`) no longer exports charts or effects** — Import from `@flikk/ui/charts` and `@flikk/ui/effects` subpaths instead.
+- **`tailwind.preset.cjs` borderRadius keys renamed** — `--form-rounded` → `--form-radius`, `--button-rounded` → `--button-radius`. Update any Tailwind config references.
+- **`ColorPickerContext` removed from public export** — Use the `useColorPicker` hook instead.
+- **`useFormStateMachine` / `stateMachine` generic default changed** — `TData = any` → `TData = unknown`. Code relying on implicit `any` typing will need explicit generic annotations.
+
+### Added
+
+- **`Switch` `size` prop** — New `sm`, `md`, `lg` size variants.
+- **`Switch` `defaultChecked`** — Uncontrolled initial checked state.
+- **`Switch` native input passthrough props** — `name`, `value`, `required`, `form`, and optional `id` (auto-generated via `useId()` when omitted).
+- **`state` prop on `InputOTP`, `CronInput`, `FileUpload`, `InputCounter`, `Mention`** — Unified validation state (`idle` / `invalid` / `disabled`) for components that previously had no validation API.
+- **`Combobox` `iconEnd` slot** — New decorator slot that hides behind the clear button when a value is selected.
+- **`Select` `contentStart` / `contentEnd` slots** — Structural decorator slots for the trigger element.
+- **`Checkbox` / `Radio` `lg` size** — New large size variant.
+- **`secondary`, `neutral`, `dark` color namespaces** — Added to the Tailwind preset for consistent utility-class access.
+- **`./layout` subpath export** — `@flikk/ui/layout` is now a valid import path.
+- **`useDarkMode` singleton hook** — Module-level singleton with one shared `MutationObserver` and N subscribers, replacing 9 inline per-component implementations (`Select`, `Combobox`, `InputTag`, `DatePicker`, `DateRangePicker`, `TimePicker`, `Tooltip`, `Popover`, `Dropdown`).
+
+### Changed
+
+- **`Tabs`** — Trigger and panel IDs scoped with `useId()` per instance, preventing duplicate DOM IDs when multiple `Tabs` instances are on the same page.
+- **`ModalTitle` / `DrawerTitle`** — Now render as `<h2>` with an overridable `as` prop for correct document outline.
+- **`FormLabel`** — Receives `state` prop in `Select`, `Combobox`, `DatePicker`, `DateRangePicker`, `Slider` so the required indicator renders correctly in invalid state.
+- **`Alert` / `Toast` ARIA roles** — Mapped to severity: `role="alert"` for error/warning, `role="status"` + `aria-live` for info/success.
+- **`Progress`** — Animates `scaleX` instead of `width` for compositor-safe performance.
+- **`NavItem`** — Uses `grid-template-columns` transition instead of `max-width` (compositor-safe).
+- **`CustomCursor`** — `useRef` for stable random colour pick, fixing Strict Mode flicker.
+- **`ThemeContext.Provider`** — Value memoised with `useMemo` to prevent unnecessary re-renders.
+- **`Modal` context value** — Memoised with `useMemo`.
+- **`Select` / `Combobox` / `InputTag` option lists** — Capped at 100 items with a refine-search prompt for performance.
+- **`RichTextEditor` handlers** — Hoisted to `useCallback` for stable references.
+- **`TableFilter` / `ColorPicker` / `ToastProvider`** — Replaced `Date.now()`/`Math.random()` keys with incrementing refs / `crypto.randomUUID()`.
+- **`useClickOutside`** — Extended to accept additional exclusion refs.
+- **`gsap` removed from `peerDependencies`** — Had zero imports in source; was an erroneous entry.
+- **`tsconfig` `moduleResolution`** — Changed from `node` to `bundler` for correct ESM resolution.
+- **Deleted `ThemeBuilder/` directory** — Orphaned directory removed from source.
+
+### Fixed
+
+- **`Textarea` / `Combobox`** — Added `aria-describedby` wired to helper/error element IDs.
+- **`Select` / `TimePicker` / `DatePicker` / `DateRangePicker` triggers** — Added `aria-invalid` and `aria-describedby`.
+- **`Checkbox` / `Radio` (solo)** — `aria-invalid` wired when `state="invalid"`.
+- **`Tree`** — Full APG keyboard navigation (`ArrowUp`/`ArrowDown`/`Home`/`End`) with roving `tabIndex`.
+- **`DragDrop`** — Complete keyboard support with `aria-live` announcements.
+- **`Breadcrumbs`** — One `<li>` per item (was a single `li.contents`).
+- **`Select` / `Combobox`** — `aria-controls` wired to real DOM IDs; option IDs added.
+- **`Popover`** — Corrected role and `aria-haspopup` attribute.
+- **`Switch`** — All interaction routed through the native input; removed redundant track `onClick`.
+- **`Sortable`** — `aria-live` reorder announcements; `ul`/`li` semantics.
+- **`Carousel`** — `inert` attribute applied to hidden slides.
+- **`Accordion`** — `ArrowDown`/`ArrowUp` keyboard navigation between triggers.
+- **`FormLabel`** — Screen-reader-only "(required)" text added alongside the visual asterisk.
+- **`Input`** — `role="alert"` on helper text element when `state="invalid"`.
+- **`Table`** — `aria-sort` on sortable `th` columns; `scope="col"`; optional `caption` prop.
+- **`Skeleton`** — `aria-hidden` on placeholder divs.
+- **`Tooltip`** — Removed `aria-live`; fixed double Tab stop via `cloneElement`.
+- **`Rating`** — `aria-hidden` on star buttons.
+- **`Pagination`** — Ellipsis rendered as `<span>` with `role="separator"`, not a `<button>`.
+- **`AlertDialog`** — Always allows `Escape` when no footer is present, preventing a keyboard trap.
+- **`Dropdown`** — Removed hardcoded `"Menu"` `aria-label` fallback.
+- **`Checkbox` / `Radio`** — Dev-mode warning when rendered without an accessible name.
+- **`Progress`** — Consumer `aria-label` override now supported.
+- **`InputCreditCard`** — Top-level `state` + `error` props for consolidated error message; internal dirty-tracking auto-clears error on re-entry; replaced `Math.random()` IDs with `useId()`.
+- **`Tabs`** — Removed duplicate `role="tablist"`; fixed `Home`/`End` navigation.
+- **`useSelectPortal` / `useScaleBackground`** — Added isomorphic `useLayoutEffect` shim (SSR-safe).
+- **`useOverlay` scroll lock/unlock** — Added `typeof window` guard (affects `Modal`, `Drawer`, `Overlay`).
+- **`ToastProvider` / `ColorPickerBody` / `ContextMenuBody`** — `document.body` access deferred until after `isClient` check.
+- **`InputAddress`** — Replaced `Math.random()` IDs with `useId()` for hydration safety.
+- **`DatePicker` / `DateRangePicker`** — Pinned `toLocaleDateString` to `'en-US'` locale for consistent SSR/CSR output.
+- **`PageTransition`** — Added `typeof window`/`document` guards.
+- **`Badge` / `SpotlightBorder`** — Replaced `window.matchMedia` with `useReducedMotion()` for SSR safety.
+- **`TabsTrigger`** — Moved Storybook animation flag read into `useEffect` + `useRef`.
+- **`Overlay`** — Replaced `useMemo` dark-mode read with `useDarkMode()` hook.
+- **`GanttSplitter` / `Slider`** — Added pointer event listener cleanup on unmount.
+- **`Segmented`** — Wrapped `updateActiveStyle` in `useCallback`.
+- **`Masonry`** — Fixed stale closure in `MutationObserver` debounce.
+- **`useNetworkStatus`** — Always initialises to `true` (optimistic SSR default).
+- **CSS export paths** — `shadcn-compat.css` and `theme.css` now correctly copied to `dist/` during build.
+
+### Docs
+
+- **`PageHeading` stories** — Added `docs.source.code` to all stories; removed redundant `WithBreadcrumbs` story.
+
+## [1.0.0-beta.23] - 2026-04-12
+
+### Added
+
+- **SidebarLogo** — New `SidebarLogo` component for sidebar branding; shows an icon in both states and animates the text label in/out on expand/collapse.
+- **Tooltip `triggerClassName`** — New prop to apply classes directly to the trigger wrapper element, separate from the tooltip bubble's `className`.
+
+### Changed
+
+- **NavItem collapse animation** — Replaced conditional render with a CSS `max-width` + `opacity` transition so the label and end-content smoothly slide out when the sidebar collapses, rather than disappearing instantly. Added `aria-hidden` on the hidden content area.
+- **Sidebar sub-component polish** — Various updates to `SidebarHeader`, `SidebarNavGroup`, `SidebarToggle`, `SidebarUserProfile`, and `SidebarContent` for layout and accessibility improvements.
+- **MCP setup docs** — Improved `get_setup` CSS section with clearer guidance on `styles.css` being the only import needed and an explicit warning against importing `theme.css` in Next.js/Vite projects.
+
+### Fixed
+
+- **Release build** — Added `prepublishOnly: "clean && build"` to `package.json` so `npm publish` always rebuilds from source; prevents stale `dist/styles.css` from shipping in a release.
+
+## [1.0.0-beta.22] - 2026-04-08
+
+### Added
+
+- **Icon component** — Consolidated `PaymentIcon`, `SocialIcon`, and `FileTypeIcon` into a single unified `Icon` component with a consistent API across all icon categories.
+- **SelectableCard standalone support** — `SelectableCard` can now be used outside a `SelectableCard.Group` via a new `standalone` prop and `useOptionalSelectableCardContext` hook.
+- **SelectableCard `indicatorPosition` prop** — Control whether the indicator (checkbox/radio) appears at the top or bottom of the card.
+- **SelectableCard `size` variants** — New `size` prop with `cardSizes` and `indicatorSizes` in the theme for consistent sizing.
+- **SelectableCard Radio/Checkbox indicators** — Radio and Checkbox components can now be used as card indicators, replacing the previous custom indicator implementation.
+- **SelectableCard exported types** — `SelectableCardIndicatorPosition` and `SelectableCardSize` are now exported from the package.
+- **SelectableCard `defaultValue`** — `SelectableCard.Group` now accepts a `defaultValue` prop for uncontrolled initial selection.
+- **ColorPicker gradient mode** — Added gradient, image, and saved colors modes with header navigation in the ColorPicker component.
+- **AuthLayout block** — New `AuthLayout` block with Storybook stories and autodocs for login/signup page scaffolding.
+- **Storybook status badges** — Components can now be tagged as `beta`, `experimental`, `deprecated`, or `new` with visual status badges in Storybook.
+
+### Changed
+
+- **Theme font-size** — Removed root `font-size` override; text size scale shifted down one step for better alignment with browser defaults.
+- **SelectableCard stories** — Rewritten with Untitled UI-inspired examples, Icon component integration, realistic copy, and corrected indicator sizing.
+- **KPI stories** — Added beta status tag.
+- **Table performance** — Optimised rendering performance and improved code quality across all table-related files.
+
+### Fixed
+
+- **ColorPicker gradient stop colors** — Gradient stop colors are now correctly reflected in the trigger input.
+- **Overlay animation** — Smoother open/close animation; eliminated scroll-lock layout shift.
+- **SelectableCard stale closures** — `handleChange` is now wrapped in `useCallback` to prevent stale closure bugs.
+- **SelectableCard RadioIndicator layout** — Wired `indicatorSizes` from theme and cleaned up RadioIndicator layout.
+
+## [1.0.0-beta.21] - 2026-03-30
+
+### Fixed
+
+- **Animated hooks order** — Moved `useMemo` calls above early returns in `Animated.Group` and `Animated.Item` to fix React Rules of Hooks violation. Memoized `motion[as]` and added `will-change` GPU hint.
+- **Animated variant allocation** — Pre-computed animation variants at module level; trimmed `visible` state to only animate properties each preset uses.
+- **Radio dot positioning** — Fixed centering with `top-1/2 left-1/2` and `-50%` transforms in motion variants. Added `dotSizes` to theme.
+- **Checkbox/Radio checked outline** — Removed `checked:outline` ring styling for a cleaner appearance (focus-visible outlines retained).
+- **Tooltip radius & border** — Halved `--tooltip-radius` to `calc(var(--radius-base) / 2)` and removed white `border-t`.
+
+## [1.0.0-beta.20] - 2026-03-29
+
+### Added
+
+- **Button `ghost` variant** — Transparent background, no border, full padding with subtle hover tint. Ideal for toolbars and icon-only actions.
+
+### Fixed
+
+- **Segmented padding & radius** — Switched from per-item margins to container padding (`p-1`), corrected inner border-radius to `calc(var(--segmented-radius) - 4px)` for perfect nested curves, and computed slider top position from button rect for proper vertical centering.
+- **Tooltip backdrop opacity** — Increased from 60%/80% to 90% for better readability.
+- **Docs CSS import path** — Fixed `global.css` → `styles.css` in CLAUDE.md and Flikkui-components.md.
+
+## [1.0.0-beta.19] - 2026-03-28
+
+### Fixed
+
+- **Popover/Dropdown layout interference** — Added `contents` display class to Dropdown and Popover root wrappers to prevent layout interference with parent containers.
+- **Popover positioning flash** — Deferred PopoverBody animation until `isReady` flag from `useSelectPortal` confirms positioning is calculated, preventing initial flash/jump.
+
+### Changed
+
+- **Separator stories** — Added `docs.source.code` to Variants story and new `CustomStyling` story with className override examples.
+
+## [1.0.0-beta.18] - 2026-03-18
+
+### Fixed
+
+- **DatePickerBody CSS variable** — Fixed broken `text-[var(--color-text-muted)` (missing closing `]`) in range mode footer.
+
+### Changed
+
+- **Tag enter animation removed** — Tags no longer scale-in on mount; exit animation preserved.
+
+## [1.0.0-beta.17] - 2026-03-18
+
+### Added
+
+- **Background assets export** — New `./bg/*` export path and `build:assets` script to copy background images into the dist folder.
+- **CustomCursor expanded exports** — Exported `CustomCursorProvider`, `CustomCursorFollow`, `useCustomCursor` hook, and all related types from the effects module.
+- **AuthLayout story docs** — Added `autodocs` tag and `docs.source.code` blocks to AuthLayout stories for copy-paste-ready usage examples.
+
+### Fixed
+
+- **Card.Body missing top padding** — When `Card.Body` is used without a preceding `Card.Header`, content no longer touches the top border. Added `first:pt-6` to `bodyStyle` and `footerStyle` in the Card theme so `:first-child` restores top padding automatically.
+- **Button type attribute order** — Moved `type="button"` before spread props so it can be overridden by consumers passing `type="submit"`.
+- **Calendar year range** — Default year dropdown now extends 10 years into the future (was capped at current year). Fixed `maxDate` year constraint logic to use `Math.max` so the dropdown always includes the max date's year.
+
+### Changed
+
+- **MCP server v0.2.0** — Added `get_setup` tool, hooks extraction, and sub-component detection. Updated README and docs to include dependency information.
+- **Tailwind config** — Removed external Google Fonts `@import` from `tailwind-config.css` to eliminate render-blocking network request.
+
+## [1.0.0-beta.16] - 2026-03-17
+
+### Added
+
+- **Flikkui MCP server** — New `packages/mcp/` workspace with a build-time extraction pipeline that parses all component source files into a structured registry. Provides 4 MCP tools (`get_component`, `search_components`, `get_theme_tokens`, `generate_code`) for AI-powered component lookup and code generation. Includes Claude Code integration instructions in README.
+
+### Changed
+
+- **Switch component** — Overhauled UI with updated theme and improved visual design (`Switch.tsx`, `Switch.theme.ts`).
+- **Slider component** — Improved layout, styling, and theming; refined theme tokens (`Slider.tsx`, `Slider.theme.ts`).
+- **StreamingResponse component** — Refined animation timings, markdown rendering, cursor behaviour, and word animation context logic.
+- **Neumorphic components** — Updated stories with revised layout; added missing exports on `InsetCircleButton` and `InsetPill`.
+- **GlassSurface component** — Fixed rendering issues and updated stories extensively; added new `GlassSurface.types.ts`.
+- **Progress component** — Minor theme token updates.
+- **Drawer stories** — Removed outdated story entries to keep documentation current.
+
+### Removed
+
+- **ThinkingIndicator component** — Removed from the `ai` module along with all associated files (theme, animations, stories, types, index).
+
+## [1.0.0-beta.15] - 2026-03-16
+
+### Added
+
+- **NeumorphicPrototype component** — New experimental neumorphic design prototype with associated stories demonstrating the neumorphic visual style.
+- **InteractiveCharacters component** — New animated character component with blob/liquid character visuals and interactive behavior.
+- **DateRangePicker component** — Full compound component with `DateRangePicker.Trigger`, `DateRangePicker.Body`, and preset support for common date ranges.
+- **FileUploadProgress component** — New file upload progress component with radial progress indicator, `completionDelay` prop for configurable tick-to-remove transition, and returns null when items array is empty. Uses `TrashIcon` for completed file removal and `XMarkIcon` for cancel.
+- **AuthLayout block story** — New login/auth layout block with page transition animation.
+- **Calendar `showOtherMonthDays` prop** — New prop to control visibility of dates from adjacent months in the calendar grid.
+- **Calendar range selection styling** — Range selection strip now uses rounded endpoints for a more polished appearance.
+- **Drawer `closeOnBack` prop** — New prop that closes the Drawer when the browser back button is pressed, using the History API.
+
+### Changed
+
+- **Progress component API simplified** — `color` prop and `colors` theme key removed. The fill bar color is now controlled via `className` (e.g. `className="bg-[var(--color-success)]"`). `trackClassName` and `fillClassName` props replaced by `wrapperClassName`. Default fill color is now always the primary CSS variable.
+- **Progress indeterminate animation** — Animation updated from `translateX` to position-based (`left`/`width`) keyframes at 1.8s linear timing. Striped pattern applied by default using `repeating-linear-gradient`.
+- **Progress label font weight** — Label changed from `font-medium` to `font-semibold` for improved legibility.
+- **Progress `labelPosition="bottom"` layout** — Changed from `flex-col-reverse` to `flex-col` to maintain consistent visual order.
+- **Modal animation** — Refined to use combined scale and slight slide-in style for a more polished entrance.
+- **Toast component** — Refactored internal structure for cleaner implementation.
+- **Button theme** — Removed `rounded-none overflow-visible` from link variant to fix layout artifacts.
+- **`dateUtils`** — Token replacement now uses placeholder-based approach to prevent collisions with month names containing format tokens (e.g. "March" containing "M").
+- **ButtonGroup single-child rounding** — Fixed border-radius removal on only-child buttons using `:not(:only-child)`.
+- **KanbanLayout, OnboardingLayout, ProfileLayout, SettingsLayout stories** — Minor story updates for consistency.
+
+### Fixed
+
+- **Badge icon sizing** — Removed `[&>svg]:size-full` rule that caused icons inside Badge to scale to the full badge size.
+- **Badge icon visibility and alignment** — Fixed icon rendering and avatar alignment issues within Badge.
+- **Badge size in Feed story** — Changed invalid `xs` size reference to `sm`.
+- **Kbd component square rendering** — Fixed Kbd not rendering as a square for single-character keys.
+- **Kbd size tokens** — Refined to 20px/24px with reduced padding for better proportions.
+- **InputOTP number clipping** — Fixed OTP digit input numbers being clipped by removing inner padding on the input container.
+- **Tag `startContent` and avatar alignment** — Fixed alignment issues when using `startContent` or avatar slots in the Tag component.
+- **Avatar title visibility** — Fixed Avatar title not displaying when a subtitle was provided without an explicit title prop.
+- **Avatar title/subtitle overflow** — Added `truncate` to prevent layout overflow when long text is used in title or subtitle slots.
+- **SelectableCard icon circle shrinking** — Fixed icon circles in SelectableCard stories shrinking unexpectedly.
+- **DateRangePicker range fix** — Corrected date range selection logic.
+- **Type safety across 35+ files** — Fixed generic defaults, XSS protections, and type safety issues identified in comprehensive code review.
+- **Accessibility improvements across 30+ files** — Addressed accessibility findings from code review including ARIA attributes and keyboard navigation.
+- **Bundle analysis cleanup** — Removed unused custom icon system (entire codebase uses Heroicons).
+- **Storybook build CSS import path** — Corrected CSS import path in Storybook preview config.
+- **Avatar and AvatarGroup minor fixes** — Various alignment and rendering corrections.
+- **CommandPalette fixes** — Minor rendering and behavior corrections.
+- **`global.scss` indeterminate progress keyframes** — Updated keyframes to use `left`/`width` properties instead of `translateX` for correct indeterminate bar behavior.
+
+### Removed
+
+- **`ApprovalCard` component** — Removed in favor of the new `InteractiveCharacters` component.
+- **`MessageHistory` component** — Removed as part of the InteractiveCharacters introduction.
+- **Unused custom icon system** — Removed all legacy custom SVG icon infrastructure; Heroicons is the only icon system.
+- **Progress `color` prop** — Use `className` to set fill color instead (see Changed section above).
+- **Progress `trackClassName` / `fillClassName` props** — Replaced by `wrapperClassName`.
+
+## [1.0.0-beta.14] - 2026-03-05
+
+### BREAKING CHANGES
+
+- **Badge `ghost` variant renamed to `soft`** — `variant="ghost"` no longer exists on Badge. Use `variant="soft"` instead. The `BadgeVariant` TypeScript type has been updated — code using `"ghost"` will fail type-checking.
+- **Button `ghost` variant renamed to `soft`** — `variant="ghost"` no longer exists on Button. Use `variant="soft"` instead. The `ButtonVariant` TypeScript type has been updated — code using `"ghost"` will fail type-checking.
+- **Sidebar API overhaul** — The Sidebar component has been significantly restructured. New compound sub-components added (`Sidebar.MobileTrigger`, `Sidebar.UserProfile`). Hardcoded colors replaced with CSS variables. Mobile full-screen takeover behavior added. If you have custom Sidebar implementations, review the new API.
+- **NavItem API changes** — NavItem now supports self-contained submenus via `items` prop, `notification` prop (number for badge, `true` for dot), and active indicator bar. The `NavItemProps` interface has changed. Hardcoded `hover:bg-neutral-100` replaced with `hover:bg-[var(--color-background-secondary)]`.
+
+### Added
+
+- **Sidebar mobile support** — Full-screen mobile takeover with backdrop, body scroll lock, and close button. New `mobileBreakpoint` prop (default 1024px).
+- **Sidebar.MobileTrigger** — New sub-component for hamburger menu button, auto-hidden on desktop.
+- **Sidebar.UserProfile** — New sub-component with avatar, name, email, status dot, and collapsed tooltip that adapts to rail/expanded/mobile states.
+- **Sidebar accordion mode** — `Sidebar.Nav` now supports accordion mode where only one submenu can be open at a time.
+- **NavItem `items` prop** — Self-contained submenu support without manual `useState` per submenu.
+- **NavItem `notification` prop** — Pass a number for a count badge or `true` for a dot indicator.
+- **NavItem active indicator** — 3px rounded primary bar on left edge for active items.
+- **NavItem focus-visible ring** — Keyboard navigation now shows a visible focus ring.
+
+### Changed
+
+- **Badge/Pill sizes and font weights** — Adjusted sizes and font weights (`xs`/`sm` now use `font-semibold`, Pill `md` padding updated).
+- **Tabs trigger font** — Changed to `font-semibold`, removed gap from size variants.
+- **Link component** — Added `font-semibold` to link variant.
+- **PromptInput width** — Changed from `min-w-xl` to `w-full` for fluid width.
+- **PromptSuggestion padding** — Reduced from `py-2 px-3.5` to `py-1 px-3`.
+- **Card/Modal radius** — Reduced from 3x to 2x base radius in `theme.css`.
+- **Sidebar theming** — All hardcoded colors (`bg-white`, `border-gray-200`) replaced with CSS variables. Supports `bg-image` classes for dark/themed sidebars via `className`.
+- **NavItem hover style** — Replaced `hover:bg-neutral-100` with `hover:bg-[var(--color-background-secondary)]` for theme consistency.
+- **Block stories** — Added responsive breakpoints and mobile sizing to AIAssistant, ActivityTimeline, Changelog, Chat, and other layout stories.
+
+### Fixed
+
+- **FileManagerLayout story** — Fixed Breadcrumbs usage (use `items` prop, not compound API).
+- **SettingsLayout story** — Removed non-existent `FormLayout.Header`/`FormLayout.Body` sub-components.
+- **Font size and CSS variables** — Fixed font size and variable references.
+
+### Removed
+
+- **EmptyStatesLayout story** — Removed story file.
+
+## [1.0.0-beta.13] - 2026-03-04
+
+### Added
+
+- **Feed compound component** — Rebuilt as `Feed.Item` + `Feed.Collapse` with SVG curved connector, staggered expand/collapse animation, and reduced-motion support. New `Feed.animations.ts` module added.
+- **Badge `xs` size** — New extra-small size variant with adjusted typography and per-size font weight.
+- **FileTypeIcon component** — New component for rendering file type indicators.
+- **ThemeBuilder component** — New component for theme customization workflows.
+- **AIOrb `Aura` variant** — New aura visual variant for the AIOrb component. `OrbState` type is now exported. Hooks directory added.
+- **GlassSurface `colorScheme` prop** — Theme-aware defaults for light mode including opacity, distortion, blend mode, and saturation control. Storybook stories added.
+- **`paletteGenerator` utility exported** — `paletteGenerator` is now exported from the main `utils` package.
+
+### Changed
+
+- **Feed architecture** — Previous Feed component replaced entirely by the new compound component API (`Feed.Item`, `Feed.Collapse`).
+- **Badge typography and alignment** — Adjusted per-size font weight, added `align-middle`, fixed `ghost-neutral` text color.
+- **Avatar base styles simplified** — Removed ring and glass-effect styles, switched to `font-bold`, limited `xs` size to single initial character.
+- **Button `sm` text size** — Changed from `text-base` to `text-sm` for small button variant.
+- **Message component** — Timestamp text changed to `text-xs`, sender bubble darkened to `neutral-900`.
+- **AIOrb container** — Changed to `overflow-visible` to allow visual effects to extend beyond container bounds.
+- **Timeline horizontal connector positioning** — Fixed using `absolute` positioning instead of `flex` layout.
+- **`--color-text-secondary` token** — Adjusted from `neutral-800` to `neutral-700` in `theme.css`.
+- **SocialIcon stories** — Updated Storybook stories.
+- **Storybook sort order** — Added "Tools" category to Storybook story sort order.
+
+### Removed
+
+- **Loader component** — The `Loader` component has been removed from the library.
+
+### Fixed
+
+- **Avatar `alt` prop renamed to `name`** — `alt` prop is now `name` across Avatar and AvatarGroup. Review issues from the refactor have been addressed.
+- **Timeline horizontal connector** — Connector now uses `absolute` positioning to correctly align with timeline items.
+- **Ghost-neutral Badge text color** — Corrected text color for `ghost` variant with `neutral` color.
+
+## [1.0.0-beta.12] - 2026-02-26
+
+### BREAKING CHANGES
+
+- **Compound component `.Content` renamed to `.Body`** — All compound components that previously used `.Content` (e.g., `Card.Content`, `Accordion.Content`, `Modal.Content`, `Drawer.Content`) now use `.Body`. Backward compatibility aliases have been removed.
+
+### Added
+
+- **DatePicker `yearRange` prop** — Year dropdown order reversed (newest first) and a new `yearRange` prop exposed for custom year range configuration.
+- **`React.ReactNode` flexibility across 14 components** — Applied the ReactNode flexibility pattern to 14 components for greater composition flexibility.
+- **Checkbox and Radio flexibility** — Enhanced Checkbox and Radio components for more flexible usage patterns.
+- **AccordionTrigger chevron customization** — New `chevron`, `chevronRotation`, and `chevronPosition` props for full control over the trigger indicator icon.
+- **FormLayout Storybook autodocs** — Added `tags: ["autodocs"]`, component description, subcomponents, and inline source code blocks to FormLayout stories.
+
+### Changed
+
+- **FormLayout simplified** — Removed dedicated `FormLayout.Header` and `FormLayout.Body` sub-components; separator injection logic moved to the root `FormLayout` component for a flatter API.
+- **Card, Button, Modal, and Drawer minor styling adjustments** — Minor theme refinements for consistency.
+
+### Fixed
+
+- **DatePicker year dropdown** — Default year dropdown now ends at current year instead of +50 years into the future.
+
+## [1.0.0-beta.11] - 2026-02-24
+
+### Added
+
+- **AccordionTrigger `iconStart` / `iconEnd` props** — Trigger now accepts a leading `iconStart` and a trailing `iconEnd` element. `iconEnd` defaults to `PlusIcon`; set to `null` to hide the indicator entirely.
+- **AccordionTrigger `iconStartRotation` / `iconEndRotation` props** — Configurable rotation degrees applied to each icon when the accordion is open. `iconEndRotation` defaults to 45 (plus-to-X); use 180 for chevrons, 90 for arrows, 0 to disable. `iconRotation` retained as a deprecated alias for `iconEndRotation`.
+- **`createTriggerIconVariants` animation factory** — New exported helper in `Accordion.animations.ts` that returns Framer Motion `Variants` for icon rotation, parameterized by target degrees.
+- **Accordion `contentInnerStyle` theme key** — `AccordionThemeOverrides` now includes `contentInnerStyle`, exposed in context, so the inner content padding can be overridden via theme. `className` on `AccordionContent` now targets the inner div instead of the outer container.
+- **Drawer `sm` size** — New `sm` size variant: 320 px wide (horizontal) / 240 px tall (vertical), capped at 90 % of the viewport.
+- **`DrawerContentProps` and `DrawerFooterProps` exported** — Both prop interfaces are now re-exported from the Drawer barrel (`index.ts`) for consumer use.
+- **Button ripple utilities exported** — `useRipple`, `getRippleColorClass`, `getRippleAnimation`, and the types `RippleEffectType`, `RippleConfig`, `Ripple` are now exported from `@flikk/ui/core` and `@flikk/ui`.
+- **`ButtonTheme` interface exported** — The `ButtonTheme` interface is now `export`ed from `Button.theme.ts` for consumers who need to extend it.
+
+### Changed
+
+- **AccordionTrigger icon rendering** — The default indicator icon (`PlusIcon`) is now rendered through the unified `iconEnd` / `renderIcon` path, removing the previous hardcoded `AnimatePresence` wrapper. Indicator motion div gains `ml-auto` to always push to the right.
+- **Accordion content `max-h`** — `data-[state=open]:max-h-[500px]` reduced to `max-h-[320px]` to limit the transition distance and prevent janky over-shoot on short content.
+- **Accordion item style** — Removed `data-[state=open]:shadow-xs` from `itemStyle`; open state no longer elevates the item card.
+- **Accordion trigger style** — Removed duplicate and conflicting utilities from `triggerStyle` string (`justify-between` duplication, redundant `cursor-pointer`, redundant `flex`).
+- **Badge font sizes simplified** — `text-xs md:text-sm` (sm) and `text-sm md:text-base` (md) replaced with flat `text-sm` and `text-base` respectively, consistent with the beta.9 base-font-size change.
+- **Button `getRippleAnimation` signature** — Changed from `(effect, layer, baseScale)` to `(effect, ripple, baseScale)` so the full `Ripple` object is available; `layer` is derived internally.
+- **Button `particle` ripple effect** — Random scale and duration values are now pre-computed at ripple creation time (`randomScale`, `randomDuration` fields on `Ripple`) and reused during render, eliminating React hydration/re-render instability from calling `Math.random()` during animation.
+- **Button `echo` ripple timeouts tracked** — Echo ripple `setTimeout` calls are now stored in `timeoutsRef` and cleared on unmount, preventing state updates on unmounted components.
+- **Button `muted` ripple color removed** — `getRippleColorClass` no longer has a `muted` case; falls through to the `default` primary color.
+- **Button disabled state consolidation** — `isDisabled` now correctly includes the native `disabled` prop (`!!disabledProp`), unifying `state="disabled"`, `state="loading"`, and native `disabled={true}` into a single flag used for all conditional logic.
+- **Button `mergedRef` stability** — The merged ref callback no longer lists `ref` in its dependency array; instead tracks the latest `ref` via `useRef<forwardedRef>` to avoid DOM detach/attach cycles on every render when an inline callback ref is passed.
+- **Button prop spread order** — `restProps` and `animationProps` are now spread before the explicit props in the JSX to ensure explicitly set values (e.g., `aria-label`, `onClick`) always take precedence over motion or consumer overrides.
+- **Button reflection gradient completed** — The inner reflection `<div>` now includes the missing `from-white/25 to-transparent` gradient classes that were accidentally omitted.
+- **Card padding simplified** — All card sub-components (`Header`, `Content`, `Footer`) use flat `p-6` instead of responsive `p-4 md:p-6`. `contentStyle` and `footerStyle` now include `pt-0` to eliminate double-spacing when `Header` is present.
+- **Card `[&>*+*]:pt-0` rule removed** — The implicit child padding override has been removed from `baseStyle`; spacing is now handled explicitly per sub-component.
+- **`CardTitle` and `CardSubtitle` render as `<div>`** — Changed from `<h3>` / `<p>` to `<div>` for maximum flexibility. Consumers who want semantic heading or paragraph elements should add them inside.
+- **`CardTitleProps` / `CardSubtitleProps` interfaces** — Extend `HTMLAttributes<HTMLDivElement>` instead of `HTMLAttributes<HTMLHeadingElement>` / `HTMLAttributes<HTMLParagraphElement>`. `children` removed from explicit props (inherited from HTMLAttributes).
+- **`CardComponent` type signatures updated** — `Title` and `Subtitle` `ForwardRefExoticComponent` ref types changed from `HTMLHeadingElement` / `HTMLParagraphElement` to `HTMLDivElement`.
+- **Drawer theme keys renamed** — `DrawerTheme.content` renamed to `inner` (the full-height flex wrapper); `DrawerTheme.body` renamed to `content` (the scrollable body region). `DrawerThemeOverrides` updated to match.
+- **Drawer position variants** — `drawerPositionVariantsWithMargin` and `drawerPositionVariantsFullWidth` now use `0` offsets (e.g., `right-0 top-0 h-full`) instead of `6` (`right-6 top-6`), removing the previously baked-in viewport gutter. Apply margin via wrapper or `className` instead.
+- **`DrawerTitle` renders as `<h2>`** — Changed from `<div>` to `<h2>` for correct document outline and screen-reader heading announcement.
+- **Drawer dark mode border** — `drawerTheme.footer` dark mode border changed from `dark:border-[var(--color-neutral-700)]` to `dark:border-[var(--color-border)]` for consistency with the theme system.
+- **Drawer stories** — Added `CustomStyling` story demonstrating `className` overrides on `Drawer.Header`, `Drawer.Content`, `Drawer.Footer`, and `Drawer.Title`. Added `sm` size button and Drawer instance to the `Variants` story. Storybook size control updated to include `"sm"` option.
+- **`global.scss` shadow** — Removed `!important` from the `.shadow-real-xl` shadow value to avoid CSS specificity side-effects.
+- **`import type` for Framer Motion `Variants`** — `Accordion.animations.ts` now uses `import type` for the `Variants` import.
+
+### Fixed
+
+- **Button ripple memory leak** — `useRipple` now creates a `timeoutsRef` and clears all pending `setTimeout` handles via a `useEffect` cleanup. Previously, timers fired after component unmount and called `setRipples` on a dead component.
+- **Button `particle` ripple render instability** — `Math.random()` was previously called inside `getRippleAnimation` during React render/re-render, producing different values each call and causing animation flicker. Random values are now stable.
+- **AccordionTrigger `AnimatePresence` removed** — The previous implementation wrapped the icon in `AnimatePresence` unnecessarily; it has been replaced with a direct `motion.div` using `initial={false}` and `animate` state, which is simpler and avoids exit animation artifacts.
+
+## [1.0.0-beta.10] - 2026-02-23
+
+### Added
+
+- **VoiceRecorder component** — New `VoiceRecorder` sub-component for `PromptInput` enabling voice recording with Web Speech API / MediaRecorder integration. Exports `VoiceRecorderProps` and `VoiceRecorderTypes` from the AI package entry point.
+- **PromptInput voice recording support** — `PromptInput` now accepts a `voiceRecorder` prop to render the `VoiceRecorder` UI inline within the input bar.
+- **PromptInput animation system** — New `PromptInput.animations.ts` file with dedicated motion variants for the prompt input component.
+- **WordAnimationContext** — New React context (`WordAnimationContext.tsx`) for coordinating per-word animation timing across `StreamingResponse` child components.
+- **StreamingResponse animation variants** — New `StreamingResponse.animations.ts` with dedicated motion variants for streaming text and markdown elements.
+
+### Changed
+
+- **Mention component — click-to-select atomic tags** — Clicking a rendered `@mention` tag now selects it as a single atomic unit with a visible ring highlight. Pressing Backspace or Delete removes the selected mention; typing any character replaces it. Implemented via React state to avoid conflicts with React reconciliation (`removeChild` errors previously caused by direct DOM manipulation).
+- **Mention component utilities** — New `Mention.utils.ts` file extracted from component logic for reuse and testability.
+- **StreamingResponse MarkdownRenderer** — Refactored `MarkdownRenderer.tsx` with improved block-level animation sequencing, better code block rendering, and compatibility with the new `WordAnimationContext`.
+- **StreamingCursor** — Enhanced `StreamingCursor.tsx` with refined animation and cursor character options.
+- **PromptInput types** — `PromptInput.types.ts` updated with new props for voice recording integration and animation configuration.
+- **StreamingResponse types** — `StreamingResponse.types.ts` updated with new animation and cursor configuration props.
+- **Tag component** — Types, theme, and implementation updated for improved flexibility and better integration with Mention's tag rendering.
+- **Core component theme adjustments** — Minor visual refinements to Avatar, Badge, Button, and Card themes for improved consistency.
+
+### Fixed
+
+- **Dropdown portal rendering** — `DropdownMenu` now correctly handles portal attachment edge cases.
+- **Popover positioning and types** — `PopoverContent` positioning logic improved; `Popover.types.ts` extended with additional placement options.
+- **useSelectPortal hook** — Refactored `useSelectPortal.ts` with more robust portal selection and cleanup logic, eliminating positioning drift on scroll and resize.
+
+## [1.0.0-beta.9] - 2026-02-20
+
+### Fixed
+
+- **Text sizing corrected across all components** — Base font size changed from `text-sm` to `text-base` throughout all component themes, matching the intended design system baseline. Affects AI components, charts, core components, data-display, forms, effects, and layout.
+- **Corrupted CSS variable references in Avatar and Segmented themes** — A previous automated script corrupted `--avatar-text-*` and `--segmented-text-size-*` variable names (e.g. `--avatar-text-sm` was corrupted to `--avatar-text-base`). These have been replaced with direct Tailwind text-size classes, which are more reliable and remove the need for the intermediate CSS variables.
+- **Unused CSS variables removed from theme.css** — `--form-text-*`, `--button-text-size-*`, `--segmented-text-size-*`, and `--avatar-text-*` variables have been removed as they are no longer referenced by any component theme.
+
+## [1.0.0-beta.8] - 2026-02-20
+
+### BREAKING CHANGES
+
+- **Checkbox compound component API** — `Checkbox` now exports as a compound component with `Checkbox.Group`. The `id` and `name` props changed from required to optional (auto-generated when omitted or inherited from group context)
+- **Radio compound component API** — `Radio` now exports as a compound component with `Radio.Group`. The `id` and `name` props changed from required to optional. The `value` prop type widened from `string` to `string | number`
+
+### Added
+
+- **CheckboxGroup compound component** — `Checkbox.Group` for managing groups of checkboxes with controlled/uncontrolled value handling, label, description, error state, vertical/horizontal orientation, and full accessibility (aria-labelledby, aria-invalid, role="group")
+- **RadioGroup compound component** — `Radio.Group` for managing groups of radios with same feature set plus `string | number` value support (role="radiogroup")
+- **Secondary semantic color** — New `secondary` color option available in Alert, Badge, Button, Progress, Spinner, KPI, Metric, CustomCursor
+- **colorUtils module** — Shared `SemanticColor` type and centralized `semanticBgColors`, `semanticTextColors`, `semanticSpinnerColors` maps, exported from `@flikk/ui`
+- **Secondary color CSS variables** — `--color-secondary-50` through `--color-secondary-950`, `--color-secondary`, and `--color-secondary-contrast` in theme.css
+
+### Fixed
+
+- **Popover scroll lag** — Replaced debounced scroll handler with `requestAnimationFrame`-synced updates so the popover tracks the trigger without visible delay during page scroll
+- **Popover internal scroll shift** — Scroll events originating inside the popover content no longer trigger position recalculation, preventing horizontal jitter when scrolling within the popover
+- **Popover stays open when trigger off-screen** — Popover now auto-closes when the trigger element scrolls out of the viewport
+
+### Changed
+
+- **Color type consolidation** — All semantic-color components now use shared `SemanticColor` from colorUtils instead of per-component color unions
+- **Component themes** — Alert, Badge, Button, Progress, Spinner, KPI, Metric, CustomCursor themes updated with secondary color variants
+- **Checkbox/Radio themes** — Extended with groupStyle, groupHorizontalStyle, groupDescriptionStyle, groupErrorStyle, groupItemsStyle
+- **Forms barrel export** — Added CheckboxGroupProps, CheckboxGroupOrientation, RadioGroupProps, RadioGroupOrientation type exports
+- **Storybook stories** — Updated for all affected components to demonstrate secondary color and compound group APIs
+
+## [1.0.0-beta.7] - 2026-02-19
+
+### Added
+
+- **Semantic contrast color system** — Introduces `--color-primary-contrast`, `--color-danger-contrast`, `--color-success-contrast`, and `--color-warning-contrast` CSS variables for configurable text color on filled semantic backgrounds. Particularly useful when the primary color is light (e.g., yellow), where the default `text-white` would be unreadable
+- **Dark mode setup documentation** — New `docs/INSTALLATION.md` section covering dark mode configuration with `@custom-variant` and `data-theme` attribute approach
+
+### Changed
+
+- **Badge component** — Replaced hardcoded `text-white` with `text-[var(--color-{semantic}-contrast)]` across all filled color variants (`primary`, `danger`, `success`, `warning`)
+- **Button component** — All filled color variant text colors now use contrast variables instead of `text-white`
+- **Calendar component** — Selected date and range highlight text uses contrast variables
+- **CommandPalette component** — Active/selected item text migrated to contrast variable
+- **MenuItem component** — Active state text color uses contrast variable
+- **OfflineIndicator component** — Indicator text uses contrast variable
+- **Progress component** — Progress bar label text uses contrast variable
+- **Timeline component** — Active marker text uses contrast variable
+- **TableFilter component** — Active filter badge text uses contrast variable
+- **PromptInput component** — Submit button text uses contrast variable
+- **`src/styles/theme.css`** — Added four new contrast variable definitions defaulting to `var(--color-neutral-50)` (near-white), overridable per-project
+
+## [1.0.0-beta.6] - 2026-02-19
+
+### Changed
+
+- **`package-lock.json` updated** — Lockfile regenerated to reflect latest resolved dependency versions
+
+## [1.0.0-beta.5] - 2026-02-19
+
+### Added
+
+- **`./theme.css` export entry** — New subpath export `@flikk/ui/theme.css` pointing to `src/theme-plugin.css`, allowing consumers to import the Tailwind theme plugin CSS directly
+- **`src/theme-plugin.css`** — Simplified theme plugin entry file containing `@source "../dist"` and `@import "./global.scss"` directives for clean Tailwind v4 integration
+
+### Changed
+
+- **`package.json` files array** — Added `src/theme-plugin.css`, `src/global.scss`, and `src/styles` to the published files list so all theme source files are available to consumers
+- **`sideEffects` declaration** — Added `./src/theme-plugin.css` to `sideEffects` to prevent tree-shaking from discarding the CSS file
+
+### Fixed
+
+- **`@custom-variant dark` directive removed** from `theme-plugin.css` — The directive caused build errors in some consumer configurations; the simplified file is now broadly compatible
+
+## [1.0.0-beta.4] - 2026-02-19
+
+### Changed
+
+- **Dependency management overhaul** — Moved `motion`, `@heroicons/react`, `clsx`, and `tailwind-merge` from `peerDependencies` to `dependencies` so they auto-install with `@flikk/ui`. Consumers no longer need to manually install these packages.
+- **3D components isolated to sub-entry point** — `AIOrb`, `Particles`, and `SpotlightBorder` are no longer exported from `@flikk/ui` or `@flikk/ui/effects`. Import them from the new `@flikk/ui/effects/3d` subpath instead:
+  ```ts
+  // Before (pulls in three.js — breaks if not installed)
+  import { AIOrb } from "@flikk/ui";
+  // After (only loads when you explicitly opt in)
+  import { AIOrb } from "@flikk/ui/effects/3d";
+  ```
+
+### Fixed
+
+- **"Module not found" errors on fresh install** — Installing `@flikk/ui` alone now works without extra dependency installs for all non-3D, non-AI components
+- **Unwanted three.js dependency** — The main bundle no longer statically imports `three`, `@react-three/fiber`, or `@react-three/drei`
+
+## [1.0.0-beta.3] - 2026-02-19
+
+### Added
+
+- **GanttChart component** - Interactive Gantt chart with Frappe Gantt-inspired features including drag-to-reschedule, dependency arrows that follow task bars during drag, task progress indicators, and full accessibility support
+- **PageLayout compound component** - Full application layout with `PageLayout.Sidebar`, `PageLayout.Header`, and `PageLayout.Content` slots; includes stagger fade-up animation for content blocks
+- **FormLayout compound component** - Structured form sections with `FormLayout.Header`, `FormLayout.Body`, `FormLayout.Section`, and `FormLayout.Footer` sub-components
+- **15 new effect and core components**:
+  - `Aurora` - Animated aurora borealis background effect
+  - `DotPattern` - Configurable dot grid background pattern
+  - `GridPattern` - Configurable grid line background pattern
+  - `MagneticElement` - Cursor-attracted magnetic hover effect
+  - `MorphingText` - Smooth text morphing animation between strings
+  - `NoiseOverlay` - Film grain / noise texture overlay effect
+  - `ParallaxSection` - Scroll-driven parallax depth sections
+  - `Particles` - Three.js / R3F particle system effect
+  - `ScrollReveal` - Scroll-triggered reveal animation wrapper
+  - `Spotlight` - Cursor-following spotlight highlight effect
+  - `StickyScroll` - Sticky scroll content reveal (text + media panels)
+  - `CountdownTimer` - Animated countdown with days/hours/minutes/seconds display
+  - `Message` and `MessageList` - Chat message bubble components with threading support
+  - `SelectableCard` and `SelectableCardGroup` - Card-style radio/checkbox selector
+  - `TransferList` - Dual-list multi-select transfer control
+- **New form components**:
+  - `CronInput` - Human-friendly cron expression builder with utility helpers
+  - `Mention` - @mention input with autocomplete dropdown
+- **New data-display folder** - Reorganised data-display components into a dedicated folder
+- **ProgressiveBlur component** - Gradient blur effect that progressively increases across an element
+- **`dateUtils`** - Shared date formatting and manipulation utilities in `/src/utils/dateUtils.ts`
+- **12 new Storybook block stories** - Full-page layout demos including AIAssistantLayout, CalendarLayout, ChangelogLayout, CommandPaletteLayout, EmptyStatesLayout, FileManagerLayout, InboxLayout, IntegrationsLayout, MailComposerLayout, MediaGalleryLayout, WaitlistLayout, and ActivityTimelineLayout
+
+### Changed
+
+- **Message component UI improvements** - Updated message bubble styling and layout
+- **ProgressiveBlur fix** - Corrected rendering artefacts in progressive blur implementation
+- **Block stories refactored** - Removed embedded sidebars from 6+ block stories for cleaner standalone demos; all stories updated to use `w-full max-w-[X]` pattern for responsive mobile viewports
+- **Story padding reduced** - Default story padding reduced; `PageHeading` made responsive
+- **Import paths updated** - All story documentation updated from `"flikkui"` to `"@flikk/ui"`
+- **Card component** - Added `CardSubtitle` sub-component; updated theme and types
+- **Modal component** - Added `ModalDescription` and `ModalSubtitle` sub-components; updated theme and types
+- **Drawer component** - Refactored with `DrawerHeader`, `DrawerTitle`, `DrawerSubtitle` sub-components; improved theme structure
+- **Badge component** - Theme refinements for better visual consistency
+- **Button component** - Theme updates aligned with design system
+- **Accordion component** - Theme improvements
+- **Checkbox and Radio components** - Theme refactors for consistency
+- **CommandPalette** - Added `CommandItem` sub-component; updated theme
+- **ContextMenu** - Added `ContextMenuItem` sub-component; updated types
+- **Dropdown** - Added `DropdownItem` sub-component; updated types
+- **Empty component** - New `Empty` state component added with theme
+- **MenuItem component** - New standalone menu item with theme
+- **Alert and AlertDialog** - Refactored types and component implementations
+- **AI components** - Added `ApprovalCard` and enhanced `PromptInput` with updated theme
+- **Layout index** - `src/components/layout/index.ts` added for clean layout exports
+- **Forms index** - `src/components/forms/index.ts` updated with all new form components
+- **Core index** - `src/components/core/index.ts` updated with all new core components
+- **`src/index.ts`** - Main package index updated to export all new components
+- **`global.scss`** - CSS variable and base style updates
+- **`theme.css` / `tailwind-config.css`** - Theme variable refinements
+
+### Fixed
+
+- **GanttChart dependency arrows** - Arrows now correctly track task bars during drag operations
+- **GanttChart polish** - Bug fixes, performance improvements, and accessibility enhancements
+- **Lint errors** - Fixed ESLint violations across multiple files; lockfile regenerated
+- **All components made responsive** - Storybook stories updated for mobile viewport compatibility
+- **DescriptionList and FormLayout responsiveness** - Improved layout on small screens
+- **Chart and effect stories** - Responsive patterns applied consistently (`w-full max-w-[X]`)
+- **AuthLayout** - Restored non-standard CSS classes after incorrect cleanup revert
+
+## [1.0.0-beta.1] - 2026-02-11
+
+### Changed
+
+- **Package renamed** from `flikkui` to `@flikk/ui` (scoped private package)
+- **Version bumped** to `1.0.0-beta.1` — fresh start under new scope
+- **Drawer improvements** — Better transition animations and `useScaleBackground` hook fixes
+- **Smooth scroll fixes** — Resolved 6 bugs in smooth scroll utility and ScrollArea integration
+
+### Fixed
+
+- Drawer component transition animation refinements
+- `useScaleBackground` hook reliability improvements
+
+## [0.2.0-beta.12] - 2026-02-09
+
+### Added
+
+- **Animated effect component** - New compound animation component with pre-built animation presets:
+  - `Animated` container component with 10+ animation presets (fade, slide, scale, flip, bounce, rotate)
+  - `Animated.Item` for animating individual child elements with stagger support
+  - Configurable stagger delays, duration, and easing curves
+  - Reduced motion support via `prefers-reduced-motion`
+  - Built on Framer Motion with smooth, performant animations
+
+### Changed
+
+- **Alert component major enhancement** - Merged Notification functionality into Alert:
+  - Added `dismissible` prop for showing close button
+  - Added `onClose` callback for handling dismissal
+  - Enhanced alert actions support with flexible button placement
+  - Improved theme structure with separate closeButton and action styles
+  - Better icon positioning and spacing
+  - Maintains all previous Alert functionality while adding notification-like behavior
+- **Toast component improvements**:
+  - Enhanced animation performance and smoothness
+  - Improved provider integration and state management
+  - Better positioning and stacking behavior
+  - Added `pauseOnHover` support to prevent auto-dismiss on hover
+- **Tag component theme refinements**:
+  - Updated color variants for better visual consistency
+  - Improved contrast ratios for accessibility
+  - Better alignment with design system color palette
+- **Badge component theme improvements**:
+  - Enhanced visual hierarchy across variants
+  - Better text contrast on colored backgrounds
+- **Package configuration**:
+  - Removed README.md from NPM package (no documentation shown on NPM page)
+  - Cleaner NPM package with only essential distribution files
+
+### Removed
+
+- **ArtifactContainer component** - Removed experimental AI artifact container component
+- **ChatInterface component** - Removed experimental chat interface component
+- **Notification component** - Functionality merged into enhanced Alert component
+- **StepperForm component** - Removed experimental stepper form component
+- **Development documentation files** - CODE_REVIEW.md and GEMINI.md removed from repository
+
+### Fixed
+
+- **Toast rendering issues** - Fixed edge cases in toast display and dismissal
+- **Component usage issues** - Various bug fixes for improved stability and reliability
+- **Theme consistency** - Resolved color and spacing inconsistencies across components
+
+## [0.2.0-beta.11] - 2026-02-09
+
+### Fixed
+
+- **Minor patches and stability improvements**
+
+## [0.2.0-beta.10] - 2026-02-09
+
+### Added
+
+- **AIOrb effect component** with two stunning variants:
+  - `AIOrb.DotSphere` - React Three Fiber implementation with animated particle sphere, wave distortion, and custom shader effects
+  - `AIOrb.Liquid` - Vanilla Three.js metallic liquid sphere with simplex noise displacement, PBR reflections, and radial-gradient masking
+- **ArtifactContainer.CanvasTab** - New tab system for Canvas pane supporting multiple canvas views with smooth tab switching animations
+- **ArtifactContainer animations** - Comprehensive motion system including:
+  - Collapsible pane animations with smooth width transitions
+  - Handle pill hover/press interactions
+  - Border glow effects for active states
+  - Tab content fade-in/slide animations
+  - Tab underline indicator with smooth tracking
+- **AspectRatio component** - Maintains consistent width/height ratio for responsive media and content (16:9, 4:3, 1:1, etc.)
+- **ScrollArea component** - Custom scrollable container with styled scrollbars, supporting vertical/horizontal/both orientations and auto/always/scroll/hover visibility modes
+- **KPI component** - Lightweight metric display with value, label, trend indicator (auto-colored positive/negative), mini bar chart visualization, and description text
+- **Rating component** - Interactive star rating with half-star support, hover preview, keyboard navigation (arrow keys), read-only/disabled modes, custom icons, and 4 color variants
+- **Timeline component** - Compound component (Timeline > Item + Marker + Content) with vertical/horizontal layouts, left/right/alternate alignment, scroll-triggered entry animations, and completed/active/pending status states
+- **RadarChart component** - SVG-based radar/spider chart with multiple overlapping data series, concentric grid rings, axis spokes, legend, and tooltip support on hover
+- **ModalStack component** - Stacked modal system displaying two modals simultaneously (back + front) with scale/brightness animations for the back modal and smooth transitions
+- **StreamingResponse animations** - Enhanced AI streaming with:
+  - Token-by-token fade-in with blur-to-sharp effect for plain text
+  - Block-level slide-in animations for markdown elements (paragraphs, code blocks, headings, lists)
+  - Animated blinking cursor (▍) shown during streaming
+  - `AnimatedText` component for performant per-token animation
+  - `StreamingCursor` component with configurable cursor character
+  - `animated` and `showCursor` props with reduced motion support
+
+### Changed
+
+- **ArtifactContainer major refactor**:
+  - Complete rewrite with compound component architecture (Container > Chat + Canvas)
+  - Added collapsible pane support with smooth animations
+  - Implemented tab system for multiple canvas views
+  - Enhanced theming with separate styles for each sub-component
+  - Improved resize handle with visual feedback and constraints
+  - Better accessibility with ARIA attributes and keyboard navigation
+- **Metric component icon handling** - Now properly preserves custom icon className while ensuring minimum `size-6` for consistency
+- **Separator component** - Renamed from Divider (breaking change in beta.9, backward compatibility removed)
+- **Chart infrastructure improvements**:
+  - RadarChart integrated with shared ChartTooltip system
+  - Enhanced tooltip positioning for radar/polar coordinates
+  - Improved hover hit areas for better UX
+- **Dependency updates** (all latest stable versions as of Feb 2026):
+  - @emotion/is-prop-valid: 1.3.1 → 1.4.0
+  - @rollup/plugin-commonjs: 28.0.2 → 29.0.0 (major)
+  - @tailwindcss/cli: 4.0.9 → 4.1.18
+  - @types/react: 19.0.10 → 19.2.13
+  - @types/three: 0.170.0 → 0.182.0
+  - motion: 12.24.0 → 12.33.0
+  - rollup: 4.34.8 → 4.57.1
+  - three: 0.170.0 → 0.182.0
+  - typescript: 5.7.3 → 5.9.3
+  - Plus 10+ other devDependencies to latest versions
+
+### Fixed
+
+- **Production build quality** - Comprehensive code review addressing 60+ issues:
+  - Fixed grayscale2 typo in global.scss (Firefox font smoothing)
+  - Set noEmitOnError: true in Rollup config (prevents shipping broken TypeScript)
+  - Converted jsx: "react" to "react-jsx" for automatic JSX transform
+  - Added forwardRef to 25+ components (Checkbox, Radio, Switch, FormLabel, FileUpload, Calendar, DragDrop, Masonry, Skeleton, Spinner, and more)
+  - Eliminated ~60 `any` types across charts, tables, and core components
+  - Added proper TypeScript types for callbacks, data items, filter values
+  - Removed !important usage from component styles
+- **TypeScript compilation errors** - Fixed pre-existing errors that were silently ignored:
+  - Fixed react-syntax-highlighter import path (removed /index.js suffix)
+  - Widened MultiSeriesData.category to accept string | number
+  - Fixed Sortable filter type narrowing and ref casting
+  - Fixed TableFilter Input value prop casting
+- **AIOrb liquid variant rendering** - Fixed CSS margin collapsing issue where canvas container margin-top affected parent positioning (added overflow: hidden to create BFC)
+- **React peer dependency** - Updated to >=18.0.0 (motion library requirement)
+- **useClickOutside hook organization** - Moved from utils/ to hooks/ (kept re-export for backward compatibility)
+
+### Removed
+
+- **Divider backward compatibility exports** - Use Separator instead (renamed in beta.9)
+- **Dead code cleanup**:
+  - Unused coreGlowFragment export from Liquid.shaders.ts
+  - .DS_Store files (now properly gitignored)
+  - Generated src/index.css from version control (Tailwind build output)
+
+## [0.2.0-beta.9] - 2026-02-05
+
+### BREAKING CHANGES
+
+- **AI components removed from main export** — `import { ChatInterface, Message, ... } from 'flikkui'` **no longer works**. AI components now require a subpath import:
+
+  ```ts
+  // Before (broken)
+  import { ChatInterface } from "flikkui";
+  // After (correct)
+  import { ChatInterface } from "flikkui/ai";
+  ```
+
+  This was done to avoid pulling in heavy optional peer dependencies (`react-markdown`, `react-syntax-highlighter`, `remark-gfm`) for users who don't use AI components.
+
+- **CLI module removed entirely** — The `flikkui` CLI (`npx flikkui init`) is gone. The library now focuses purely on components. Remove any CLI-related scripts or dependencies.
+
+- **Input theme interface changed** — `InputTheme` now requires two new properties: `inputGroupFocusStyle` and `inputGroupFocusInvalidStyle`. If you provide a custom `InputTheme` override, you must add these fields. Focus styling is now JS-driven (not CSS `focus-within`) for better compatibility with `contentStart`/`contentEnd` slots.
+
+- **Input `states.invalid` changed** — No longer includes `focus-within` pseudo-class styles. Focus ring for invalid state is now controlled separately via `inputGroupFocusInvalidStyle`.
+
+### Added
+
+- `useIsClient` hook for safe client-side rendering and hydration detection
+- Chart path utilities (`path-utils.ts`) — shared SVG curve generation (monotone, linear, step, etc.) extracted from individual chart components
+- Comprehensive stories for Input, AreaChart, BarChart, LineChart, ComboChart
+- InputAddress: new type props and enhanced address field capabilities
+
+### Changed
+
+- Refactored chart components with simplified, shared architecture:
+  - AreaChart, BarChart, LineChart, ComboChart, StackedBarChart all use shared path/rendering utilities
+  - BarRenderer: more robust rendering with improved edge-case handling
+  - YAxis: uses `generateNiceTicks` for cleaner axis labels
+  - ChartContainer, ChartTooltip, LineRenderer: simplified internals
+- Chart validation utilities expanded with stricter data checks
+- Input component: new focus-management system using JS state instead of CSS `focus-within` for full compatibility with embedded interactive elements (`contentStart`/`contentEnd`)
+- Input `contentStartStyle` / `contentEndStyle` now reset nested interactive element styles (outline, ring, border, background) for seamless embedding
+- Simplified `index.css` — removed redundant style rules
+- Updated `theme.css` variable structure
+- Optimized `rollup.config.js` build pipeline
+- Removed CLI-related dependencies from `package.json`
+
+### Fixed
+
+- **Portal hydration mismatch (SSR/CSR)** — Fixed in 10+ components by gating portal rendering behind `useIsClient`. Affected components: ContextMenu, Dropdown, Popover, ColorPicker, Combobox, DatePicker, TimePicker, Toast, Tooltip, Overlay
+- Chart rendering edge cases and data validation errors
+- Input theme inheritance when using custom theme overrides
+- ProgressiveBlur component rendering improvements
+
+### Removed
+
+- `src/cli/` module and all associated files (init command, project detection, CSS injection, dependency installer, Tailwind setup, logger)
+- CLI dependencies removed from `package.json`
+- Unused chart hook dependencies from `useChartScales`
+
+## [0.2.0-beta.8] - 2026-01-XX
+
+### Added
+
+- Initial chart component implementations
+- Core component suite
+
+### Changed
+
+- Various component improvements and refinements
+
+## [0.2.0-beta.7] - 2026-01-XX
+
+### Changed
+
+- Component updates and bug fixes
+
+## [0.2.0-beta.6] - 2026-01-XX
+
+### Added
+
+- MenuItem component with standardized design
+- Component radii standardization using CSS variables
+
+### Changed
+
+- Comprehensive dark mode styling for Storybook documentation
+- Refactored global CSS variables for better theme consistency
+
+### Fixed
+
+- Toast component rendering and positioning issues
+
+## [0.2.0-beta.5] - 2025-12-XX
+
+### Added
+
+- Separate `theme.css` for better style organization
+
+### Changed
+
+- Complete Table component refactor with improved architecture
+- Enhanced table theming and customization options
+
+## [0.2.0-beta.4] - 2025-12-XX
+
+### Added
+
+- Progress component for loading states
+
+### Changed
+
+- Tag Input component refactor with improved API
+- Combobox component updates for better usability
+
+### Fixed
+
+- Time Picker component issues
+
+## [0.2.0-beta.3] - 2025-12-XX
+
+### Added
+
+- Initial beta release features
+
+## [0.2.0-beta.2] - 2025-12-XX
+
+### Changed
+
+- Early beta improvements
+
+## [0.2.0-beta.1] - 2025-12-XX
+
+### Added
+
+- First beta release of Flikkui
+- Core component library foundation
+- TypeScript support
+- Tailwind CSS v4 integration
+- Framer Motion animations
+- Storybook documentation
+
+---
+
+## Release Notes
+
+### Beta Release Status
+
+Flikkui is currently in beta. APIs may change between releases. Production use is not recommended until v1.0.0 stable release.
+
+### Migration Guide
+
+For migration guidance between versions, please refer to the [documentation](https://github.com/yourusername/flikkui).
+
+### Reporting Issues
+
+Found a bug? Please [open an issue](https://github.com/yourusername/flikkui/issues) on GitHub.