phlex_kit 0.2.0 → 0.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d165b8e5ecbb24ef238be1c9472db2d19cdcb30079c85e2e839019547d5324fa
-  data.tar.gz: 89f8058734e7d2745b3ea96e32cea6845e721c4f2e28a8621bc7c4978183c510
+  metadata.gz: 0f6988a4f8e3f47462f9f83824ed6542cafded9d656adb10340e7eb618156063
+  data.tar.gz: ca293b01074cfa84962df3c80683e3df5ae36cf5a919b1e8c0bcd1861948b52c
 SHA512:
-  metadata.gz: 2c1b8608a4175ae249ed98ecae2c0ffccbb1c8a5f07d9fea298bf29e39d0eee3f401f6accd822da8fb42cc194560690fa4ed72e389bd448e89d2f6f008f494de
-  data.tar.gz: 87773e1fa4628d51cdeef7d93684fe3c91d728fe77f80d3e093fbcfeb1d210d1e176d6fd0f3d89901bb7c2c4ffc67db04104fc44437a017ee7df8cd5d9ca3037
+  metadata.gz: fd26ed3b6aef6bf015c7fbdf574516a68e8eb10fe1cfe1356a4292420d01917977428d2b35a301b65e6a8ff19c73daf5ac9ffdfb9af6abae6f96afd4818d7c81
+  data.tar.gz: 6d6c3d42730c2ce500a6f8c8e49afab8e11ec192f87bf9d87434761d334b40e1a762cc157ad7b38b2914edbffeae9fea501235f1cdc0ec6937c88a8f843399fa

data/README.md

@@ -1,18 +1,28 @@
 # PhlexKit
 
-A [ruby_ui](https://ruby-ui.com)-style component kit for [Phlex](https://phlex.fun),
-styled with **vanilla CSS + design tokens instead of Tailwind**, and built so
-[phlex-reactive](https://github.com/mhenrixon/phlex-reactive) is an *optional,
-per-component* integration — never a required dependency.
-
-- **No build step.** Components ship as plain Ruby classes with co-located vanilla
-  CSS. No Tailwind, no Node, no PostCSS. Assets are precompiled-static in the gem.
-- **Theme with CSS custom properties.** Every component reads `--pk-*` tokens via
-  `var()` + `color-mix()`. Redefine `:root` and the whole kit re-themes live —
-  including dark/light/system — with no rebuild.
-- **Reactive when you want it.** Components pass `**attrs` straight through Phlex's
-  `mix`, so a phlex-reactive `**on(:event)` bundle composes onto the root element
-  with zero coupling. Non-reactive components never touch phlex-reactive.
+[![Gem Version](https://img.shields.io/gem/v/phlex_kit)](https://rubygems.org/gems/phlex_kit)
+[![CI](https://github.com/MatthewKennedy/phlex_kit/actions/workflows/ci.yml/badge.svg)](https://github.com/MatthewKennedy/phlex_kit/actions/workflows/ci.yml)
+
+A [shadcn/ui](https://ui.shadcn.com)-grade component kit for
+[Phlex](https://phlex.fun) + Rails, styled with **vanilla CSS + design tokens
+instead of Tailwind**. The full [ruby_ui](https://ruby-ui.com) catalog plus
+shadcn's own additions — 70 component families, 38 Stimulus controllers —
+with the default theme lifted verbatim from shadcn/ui's current token system.
+
+- **No build step.** Components are plain Ruby classes with co-located vanilla
+  CSS, served precompiled-static through Propshaft. No Tailwind, no Node, no
+  PostCSS.
+- **The shadcn look, themeable.** Every component reads `--pk-*` custom
+  properties. The default palette, radii, and control geometry match
+  ui.shadcn.com; redefine `:root` and the whole kit re-themes live — dark,
+  light, and system included.
+- **`@hotwired/stimulus` only.** Every interactive component works with one
+  registration call. The JS dependencies the upstream kits lean on
+  (floating-ui, embla, fuse.js, vaul, Radix, chart.js, …) are all replaced
+  with small vanilla equivalents — or, for charts, left to the host.
+- **Reactive when you want it.** Components pass `**attrs` straight through
+  Phlex's `mix`, so a [phlex-reactive](https://github.com/mhenrixon/phlex-reactive)
+  `**on(:event)` bundle composes onto the root element with zero coupling.
 
 ## Install
 
@@ -28,7 +38,19 @@ bin/rails g phlex_kit:install
 
 The installer adds `@import url("phlex_kit/phlex_kit.css");` to your
 `application.css`, drops `config/initializers/phlex_kit.rb`, and prints the
-Stimulus wiring. That's it — no Tailwind config, no content globs.
+Stimulus wiring. Then register the controllers once in your Stimulus
+entrypoint:
+
+```js
+// app/javascript/application.js
+import { Application } from "@hotwired/stimulus"
+import { registerPhlexKitControllers } from "phlex_kit/controllers"
+
+const application = Application.start()
+registerPhlexKitControllers(application)
+```
+
+That's it — no Tailwind config, no content globs, no bundler.
 
 ## Usage
 
@@ -38,14 +60,41 @@ render PhlexKit::Button.new(variant: :primary, size: :lg) { "Save changes" }
 render PhlexKit::Card.new do
   render PhlexKit::CardHeader.new do
     render PhlexKit::CardTitle.new { "Team" }
+    render PhlexKit::CardDescription.new { "Invite and manage members." }
   end
   render PhlexKit::CardContent.new { "…" }
 end
 
-render PhlexKit::Badge.new(variant: :success) { "Live" }
+render PhlexKit::Badge.new(variant: :secondary) { "Live" }
+```
+
+A form field with client-side live validation (fills the error once the
+browser flags the control invalid, clears it as the user types):
+
+```ruby
+render PhlexKit::Form.new(action: "/users", method: "post") do
+  render PhlexKit::FormField.new do
+    render PhlexKit::FormFieldLabel.new(for: "email") { "Email" }
+    render PhlexKit::Input.new(
+      type: :email, id: "email", name: "email", required: true,
+      data: { value_missing: "Email is required." }
+    )
+    render PhlexKit::FormFieldError.new
+  end
+  div(class: "pk-form-actions") do
+    render PhlexKit::Button.new(type: :submit) { "Create account" }
+  end
+end
+```
+
+A toast, spawned from anywhere (mount `PhlexKit::ToastRegion.new(flash: flash)`
+once at the end of `<body>` — server flash messages render as toasts too):
+
+```js
+PhlexKit.toast.success("Saved", { description: "Your changes are live." })
 ```
 
-Prefer revue-style `UI::Button`? Turn on the alias in the initializer:
+Prefer `UI::Button`? Turn on the alias in the initializer:
 
 ```ruby
 PhlexKit.configure { |c| c.define_ui_alias = true }   # UI == PhlexKit
@@ -53,42 +102,93 @@ PhlexKit.configure { |c| c.define_ui_alias = true }   # UI == PhlexKit
 
 ## Theming
 
-The gem ships a default dark/light/system token set (`_tokens.css`). Override any
-token in your own stylesheet — your app's CSS sorts ahead of the gem's, so you win:
+The gem ships shadcn/ui's default (neutral) token set — dark by default, light
+via `<html data-theme="light">`, OS-following via `data-theme="system"`.
+Override any token in your own stylesheet; your app's CSS sorts ahead of the
+gem's, so you win:
 
 ```css
 @import url("phlex_kit/phlex_kit.css");
 
 :root {
-  --pk-brand: #3b5bdb;
-  --pk-radius: 6px;
+  --pk-brand: #3b5bdb;      /* primary buttons, selected states, slider fill */
+  --pk-radius: 0.375rem;    /* every component radius derives from this */
 }
 ```
 
-Want a completely custom palette? Delete the `_tokens` import line from your
-manifest and define the `--pk-*` properties yourself. Every component has a
-literal fallback in `var(--pk-*, …)`, so nothing breaks if a token is missing.
+The full token surface: `--pk-bg`, `--pk-surface`, `--pk-surface-2`,
+`--pk-accent` (hover fills), `--pk-border`, `--pk-input` (control borders),
+`--pk-ring` (focus rings), `--pk-text`, `--pk-text-2`, `--pk-muted`,
+`--pk-brand`, `--pk-brand-ink`, `--pk-green`, `--pk-amber`, `--pk-red`,
+`--pk-chart-1..5`, `--pk-radius`, plus `--pk-font-sans` / `--pk-font-mono`
+(system stacks by default — override them after an @font-face to adopt Geist
+like shadcn, as the docs site does). Want a fully custom palette? Drop the
+`_tokens.css` import and define them all yourself.
 
-## Interactive components (Stimulus)
+Prefer a ready-made palette? The gem ships theme files under
+`app/assets/stylesheets/phlex_kit/themes/` (`neutral`, `zinc`, `claude`) —
+link one after the manifest and the cascade re-themes everything:
 
-Dialog, Dropdown, Select, and Avatar ship plain Stimulus controllers (no
-phlex-reactive needed). Register them once in your Stimulus entrypoint:
+```ruby
+stylesheet_link_tag "phlex_kit/phlex_kit"
+stylesheet_link_tag "phlex_kit/themes/neutral"
+```
 
-```js
-import { registerPhlexKitControllers } from "phlex_kit/controllers"
-registerPhlexKitControllers(application)
+The three knobs from ui.shadcn.com/create map directly: **Radius** →
+`--pk-radius`; **Icon Library** → `PhlexKit.config.icon_library` (see Icons
+below); **Menu** → `PhlexKit::Sidebar.new(menu: :default | :solid)`.
+
+## Icons
+
+Every built-in glyph renders through `PhlexKit::Icon`, which draws from a
+vendored icon library — pick one kit-wide in an initializer:
+
+```ruby
+PhlexKit.configure do |c|
+  c.icon_library = :tabler   # :lucide (default), :tabler, :phosphor, :remix
+end
 ```
 
-## phlex-reactive (optional)
+Use it directly with canonical semantic names (the per-library vocabulary is
+pre-resolved — `:chevron_down` is Phosphor's `caret-down`, Remix's
+`arrow-down-s-line`, and so on):
+
+```ruby
+render PhlexKit::Icon.new(:calendar)                     # 16px, configured library
+render PhlexKit::Icon.new(:search, size: 24)
+render PhlexKit::Icon.new(:check, library: :phosphor)    # per-instance override
+```
 
-For components that own server-state behavior (live counters, moderation queues,
-cross-tab updates), add phlex-reactive and include its mixin in a component:
+`PhlexKit::Icons.names` lists the full catalog (~70 glyphs, all guaranteed to
+resolve in all four libraries); unknown names fail loud. HugeIcons is not
+included — its free set forbids redistributing the artwork inside a gem. Icon
+path data licenses ship in `THIRD_PARTY_LICENSES` (Lucide ISC, Tabler MIT,
+Phosphor MIT, Remix Apache-2.0).
+
+## Charts
+
+`PhlexKit::Chart` is deliberately a thin wrapper — **no charting library is
+bundled**. Expose [Chart.js](https://www.chartjs.org) as `window.Chart` (a
+vendored UMD file and one `javascript_include_tag` is enough) and the kit
+builds the chart with shadcn-style theming: series colored from
+`--pk-chart-1..5`, translucent area fills, hairline grids, re-rendering on
+theme change.
 
 ```ruby
-# Gemfile
-gem "phlex-reactive"
+render PhlexKit::Chart.new(options: {
+  type: "line",
+  data: { labels: %w[Jan Feb Mar], datasets: [ { label: "Orders", data: [3, 7, 4], fill: true } ] }
+})
 ```
 
+No `window.Chart`? The controller dispatches `phlex-kit--chart:connect` with
+`{ canvas, options }` so you can drive any other library.
+
+## phlex-reactive (optional)
+
+For components that own server-state behavior, add phlex-reactive and include
+its mixin — PhlexKit does **not** depend on it:
+
 ```ruby
 class MyCounter < PhlexKit::BaseComponent
   include Phlex::Reactive::Component
@@ -97,8 +197,7 @@ class MyCounter < PhlexKit::BaseComponent
 end
 ```
 
-PhlexKit does **not** depend on phlex-reactive. `PhlexKit.reactive?` auto-detects
-it; set `config.reactive` to force it on/off.
+`PhlexKit.reactive?` auto-detects the gem; set `config.reactive` to force it.
 
 ## Ejecting components (shadcn-style)
 
@@ -111,25 +210,87 @@ bin/rails g phlex_kit:component button
 This copies `button.rb` + `button.css` into `app/components/phlex_kit/button/`
 and wires its `@import`. Your copy shadows the gem's.
 
-## How the asset wiring works
+## The docs site
 
-Three engine initializers reproduce the pattern proven in production (revue):
+The dummy Rails app is a full shadcn-style docs site: a sidebar menu with one
+page per component, every use case demoed with a Preview/Code toggle (the code
+shown is extracted from the running example source, so it can never drift).
+A one-page kitchen-sink gallery lives at /gallery:
 
-1. `app/components` and the stylesheet dir go on Propshaft's load path so CSS can
-   sit beside each `.rb`.
-2. Component folders are Zeitwerk-`collapse`d, so `button/button.rb` is
-   `PhlexKit::Button` (not `PhlexKit::Button::Button`) and `card/card_header.rb`
-   is `PhlexKit::CardHeader`.
-3. A private-method guard keeps Propshaft from serving Ruby source out of
-   `public/assets/` (covered by `test/assets/asset_load_path_test.rb`).
+```bash
+git clone https://github.com/MatthewKennedy/phlex_kit && cd phlex_kit
+bundle install
+bundle exec puma -p 3999 test/dummy/config.ru
+# open http://127.0.0.1:3999
+```
+
+By default the docs site renders the shadcn-parity baseline (default tokens,
+lucide icons). Two env vars re-skin the whole site, handy for eyeballing a
+theme or icon set across every component:
+
+```bash
+# Boot with a bundled theme (neutral, zinc, or claude)
+PK_THEME=claude bundle exec puma -p 3999 test/dummy/config.ru
+
+# Boot with a different icon library (lucide is the default; tabler, phosphor, remix)
+PK_ICONS=tabler bundle exec puma -p 3999 test/dummy/config.ru
+
+# Or both
+PK_THEME=zinc PK_ICONS=phosphor bundle exec puma -p 3999 test/dummy/config.ru
+```
 
-Only the `@import url("…")` form is fingerprinted by Propshaft — a bare
-`@import "…"` ships un-digested and 404s. The manifest always uses `url()`.
+`PK_THEME` links the matching file from
+`app/assets/stylesheets/phlex_kit/themes/` after the manifest — the same
+mechanism a host app uses. Light/dark/system switching is in the site's
+header regardless of theme.
 
 ## Components
 
-See [ROADMAP.md](ROADMAP.md) for the full inventory and porting status.
+Everything in ruby_ui (53/53) plus shadcn/ui's own catalog: accordion, alert,
+alert dialog, aspect ratio, attachment, avatar (+ group), badge, breadcrumb,
+bubble, button, button group, calendar, card, carousel, chart, checkbox,
+clipboard, codeblock, collapsible, combobox (button/input/badge-chip
+triggers), command palette, context menu, data table, date picker, dialog,
+drawer, dropdown menu, empty, form + form field, hover card, input, input
+group, input OTP, item, kbd, label, link, masked input, menubar, message,
+message scroller, native select, navigation menu, pagination, popover,
+marker, progress, radio button + radio group, resizable, scroll area, select,
+separator, sheet, shortcut key, sidebar, skeleton, slider, spinner,
+switch, table, tabs, textarea, theme toggle, toast (sonner-style), toggle,
+toggle group, tooltip, typography.
+
+Plus two utility classes: `.pk-shimmer` (gradient sweep for loading text) and
+`.pk-scroll-fade` (edge-masked scroll containers, position-aware via the
+`phlex-kit--scroll-fade` controller).
+
+Inventory and porting notes: [ROADMAP.md](ROADMAP.md). Architecture and
+conventions: [docs/](docs/).
+
+## RTL
+
+shadcn's `Direction` is a React context provider; PhlexKit needs none — set
+`dir="rtl"` on `<html>` and browser layout handles the flex/grid flows. Note
+the caveat: popover-style panels anchor with physical `left`/`top` offsets, so
+fully mirrored overlay alignment in RTL may need small host-side overrides.
+
+## How the asset wiring works
+
+Four engine initializers make the zero-build story hold:
+
+1. `app/components`, the stylesheet dir, and `app/javascript` go on
+   Propshaft's load path, so CSS sits beside each `.rb` and the importmap pins
+   resolve.
+2. Component folders are Zeitwerk-`collapse`d, so `button/button.rb` is
+   `PhlexKit::Button` and `card/card_header.rb` is `PhlexKit::CardHeader`.
+3. A guard keeps Propshaft from serving Ruby source out of `public/assets/`.
+4. The gem's importmap (pinning every controller) is appended to the host's.
+
+Manifest imports use the `@import url("…")` form (Propshaft only fingerprints
+`url()`) with paths relative to the manifest's own directory — both guarded by
+tests.
 
 ## License
 
-MIT.
+MIT. Component design ported from [ruby_ui](https://github.com/ruby-ui/ruby_ui)
+and [shadcn/ui](https://ui.shadcn.com) (both MIT), with attribution comments
+retained per component.

data/THIRD_PARTY_LICENSES

@@ -0,0 +1,104 @@
+Third-party licenses for icon path data vendored under lib/phlex_kit/icons/
+(generated by scripts/generate_icons.rb; the gem's own code is MIT — see
+MIT-LICENSE). HugeIcons is deliberately not included: its free set's usage
+terms forbid editing and redistribution of the artwork.
+
+--------------------------------------------------------------------------------
+Lucide (lib/phlex_kit/icons/lucide.rb)
+Source: https://github.com/lucide-icons/lucide
+License: ISC
+
+ISC License
+
+Copyright (c) for portions of Lucide are held by Cole Bemis 2013-2022 as part
+of Feather (MIT). All other copyright (c) for Lucide are held by Lucide
+Contributors 2022.
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.
+
+--------------------------------------------------------------------------------
+Tabler Icons (lib/phlex_kit/icons/tabler.rb)
+Source: https://github.com/tabler/tabler-icons
+License: MIT
+
+MIT License
+
+Copyright (c) 2020-2024 Paweł Kuna
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+--------------------------------------------------------------------------------
+Phosphor Icons (lib/phlex_kit/icons/phosphor.rb)
+Source: https://github.com/phosphor-icons/core
+License: MIT
+
+MIT License
+
+Copyright (c) 2023 Phosphor Icons
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+--------------------------------------------------------------------------------
+Remix Icon (lib/phlex_kit/icons/remix.rb)
+Source: https://github.com/Remix-Design/RemixIcon
+License: Apache License 2.0
+
+Copyright RemixIcon contributors.
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may not
+use the vendored icon data except in compliance with the License. You may
+obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+License for the specific language governing permissions and limitations under
+the License.
+
+NOTICE (statement of changes, per Apache-2.0 §4): the vendored data is
+extracted SVG path geometry only, converted to Ruby literals and keyed by
+PhlexKit's canonical glyph names; visual geometry is unmodified.

data/app/assets/stylesheets/phlex_kit/_tokens.css

@@ -1,6 +1,69 @@
 /* Kit utilities used by the interactive controllers (Stimulus toggles these). */
 .pk-hidden { display: none !important; }
 
+/* Shimmer — shadcn's shimmer util: a highlight band sweeping across text, for
+   loading / "thinking…" states. Pure CSS, built on currentColor: the text keeps
+   its own color (any color) and the highlight derives from it via relative
+   color syntax, so it brightens automatically in dark mode. Tune per element
+   with inline custom properties:
+     --pk-shimmer-color     highlight (default: brightened currentColor)
+     --pk-shimmer-duration  one sweep (default 2s)
+     --pk-shimmer-spread    band width (default 3ch + 40px)
+     --pk-shimmer-angle     band tilt (default 20deg)
+   Modifiers: .once (single sweep), .reverse. Honors prefers-reduced-motion and
+   falls back to plain text in browsers without relative color support. */
+.pk-shimmer {
+  --pk-shimmer-color: oklch(from currentColor calc(l + .25) c h);
+  --pk-shimmer-duration: 2s;
+  --pk-shimmer-spread: calc(3ch + 40px);
+  --pk-shimmer-angle: 20deg;
+  background-image:
+    linear-gradient(calc(90deg + var(--pk-shimmer-angle)),
+      transparent calc(50% - var(--pk-shimmer-spread) / 2),
+      var(--pk-shimmer-color) 50%,
+      transparent calc(50% + var(--pk-shimmer-spread) / 2)),
+    linear-gradient(currentColor, currentColor);
+  background-size: 250% 100%, auto;
+  background-repeat: no-repeat;
+  -webkit-background-clip: text;
+  background-clip: text;
+  -webkit-text-fill-color: transparent;
+  animation: pk-shimmer var(--pk-shimmer-duration) linear infinite;
+}
+.pk-shimmer.once { animation-iteration-count: 1; animation-fill-mode: forwards; }
+.pk-shimmer.reverse { animation-direction: reverse; }
+[dir="rtl"] .pk-shimmer { animation-direction: reverse; }
+[dir="rtl"] .pk-shimmer.reverse { animation-direction: normal; }
+@keyframes pk-shimmer {
+  from { background-position: 250% 0, 0 0; }
+  to { background-position: -150% 0, 0 0; }
+}
+@media (prefers-reduced-motion: reduce) {
+  .pk-shimmer { animation: none; background-image: none; -webkit-text-fill-color: currentColor; }
+}
+@supports not (color: oklch(from white l c h)) {
+  .pk-shimmer { animation: none; background-image: none; -webkit-text-fill-color: currentColor; }
+}
+
+/* Scroll fade — shadcn's scroll-fade util: masks the edges of a scrollable
+   container while there is more content in that direction. Pair with the
+   phlex-kit--scroll-fade controller, which toggles data-at-start/data-at-end. */
+.pk-scroll-fade {
+  --pk-scroll-fade-size: 2rem;
+  overflow-y: auto;
+  mask-image: linear-gradient(to bottom,
+    transparent 0, black var(--pk-scroll-fade-size),
+    black calc(100% - var(--pk-scroll-fade-size)), transparent 100%);
+}
+.pk-scroll-fade[data-at-start] {
+  mask-image: linear-gradient(to bottom,
+    black calc(100% - var(--pk-scroll-fade-size)), transparent 100%);
+}
+.pk-scroll-fade[data-at-end] {
+  mask-image: linear-gradient(to bottom, transparent 0, black var(--pk-scroll-fade-size));
+}
+.pk-scroll-fade[data-at-start][data-at-end] { mask-image: none; }
+
 /* Kit elements size predictably: width includes padding + border, so
    `width: 100%` controls (inputs, triggers, option rows) never overflow their
    container. Scoped to pk-* classes and their subtrees — the host's own box
@@ -22,6 +85,13 @@
    var(--pk-*), so redefining :root after the import re-themes the whole kit
    with no rebuild.
 
+   Optional sidebar overrides (shadcn sidebar-* parity) — deliberately NOT
+   defined here: --pk-sidebar / -text / -accent / -border / -primary /
+   -primary-ink. sidebar.css consumes them via token→token fallbacks
+   (e.g. var(--pk-sidebar-primary, var(--pk-brand))), so unset they fall back
+   to surface/text/accent/border/brand/brand-ink; a theme sets one only when
+   its value differs from the shared token.
+
    Dark is the default; light is opt-in via <html data-theme="light"> (set it
    server-side to avoid a flash). "system" follows the OS via prefers-color-scheme.
    Keep the two light token sets in sync. */
@@ -47,6 +117,8 @@
   --pk-chart-4: #1d4ed8;
   --pk-chart-5: #1e40af;
   --pk-radius: 0.625rem;
+  --pk-font-sans: ui-sans-serif, system-ui, -apple-system, sans-serif;
+  --pk-font-mono: ui-monospace, SFMono-Regular, Menlo, monospace;
   color-scheme: dark;
 }
 

data/app/assets/stylesheets/phlex_kit/phlex_kit.css

@@ -50,6 +50,7 @@
 @import url("kbd/kbd.css");
 @import url("label/label.css");
 @import url("link/link.css");
+@import url("marker/marker.css");
 @import url("menubar/menubar.css");
 @import url("message/message.css");
 @import url("message_scroller/message_scroller.css");
@@ -70,7 +71,6 @@
 @import url("skeleton/skeleton.css");
 @import url("slider/slider.css");
 @import url("spinner/spinner.css");
-@import url("stars/stars.css");
 @import url("switch/switch.css");
 @import url("table/table.css");
 @import url("tabs/tabs.css");

data/app/assets/stylesheets/phlex_kit/themes/claude.css

@@ -0,0 +1,86 @@
+/* PhlexKit theme: Claude — warm ivory/charcoal neutrals + terracotta brand,
+   after the claude.ai palette. Pure token override: load AFTER the
+   phlex_kit.css manifest (stylesheet_link_tag "phlex_kit/themes/claude")
+   and the cascade re-themes every component; no component CSS is touched.
+
+   Same contract as _tokens.css: dark is the default, light is opt-in via
+   <html data-theme="light">, "system" follows the OS. Keep the two light
+   blocks in sync.
+
+   Anthropic's brand faces (Styrene, Tiempos/Copernicus) are licensed and
+   not shipped; --pk-font-serif falls back through Georgia. A host that has
+   the real fonts re-points the token. */
+:root {
+  --pk-bg: #262624;
+  --pk-surface: #30302e;
+  --pk-surface-2: #3a3a37;
+  --pk-accent: #45453f;
+  --pk-border: #faf9f51f;
+  --pk-input: #faf9f52e;
+  --pk-ring: #d97757;
+  --pk-text: #f5f4ee;
+  --pk-text-2: #d9d8d0;
+  --pk-muted: #a3a094;
+  --pk-brand: #d97757;
+  --pk-brand-ink: #ffffff;
+  --pk-green: #22c55e;
+  --pk-amber: #f59e0b;
+  --pk-red: #ff6568;
+  --pk-chart-1: #ecb4a0;
+  --pk-chart-2: #e19477;
+  --pk-chart-3: #d97757;
+  --pk-chart-4: #b85c3e;
+  --pk-chart-5: #8f4630;
+  --pk-radius: 0.75rem;
+  --pk-font-serif: "Copernicus", "Tiempos Text", Georgia, "Times New Roman", serif;
+  color-scheme: dark;
+}
+
+:root[data-theme="light"] {
+  --pk-bg: #faf9f5;
+  --pk-surface: #ffffff;
+  --pk-surface-2: #f0eee6;
+  --pk-accent: #f0eee6;
+  --pk-border: #e5e2d9;
+  --pk-input: #d9d6ca;
+  --pk-ring: #d97757;
+  --pk-text: #1f1e1d;
+  --pk-text-2: #4a4844;
+  --pk-muted: #83817b;
+  --pk-brand: #d97757;
+  --pk-brand-ink: #ffffff;
+  --pk-green: #16a34a;
+  --pk-amber: #d97706;
+  --pk-red: #d13415;
+  color-scheme: light;
+}
+
+@media (prefers-color-scheme: light) {
+  :root[data-theme="system"] {
+    --pk-bg: #faf9f5;
+    --pk-surface: #ffffff;
+    --pk-surface-2: #f0eee6;
+    --pk-accent: #f0eee6;
+    --pk-border: #e5e2d9;
+    --pk-input: #d9d6ca;
+    --pk-ring: #d97757;
+    --pk-text: #1f1e1d;
+    --pk-text-2: #4a4844;
+    --pk-muted: #83817b;
+    --pk-brand: #d97757;
+    --pk-brand-ink: #ffffff;
+    --pk-green: #16a34a;
+    --pk-amber: #d97706;
+    --pk-red: #d13415;
+    color-scheme: light;
+  }
+}
+
+/* The one non-token rule: Claude's signature serif display over a sans body.
+   Serifs carry less inherent weight than the sans they replace, so headings
+   ease off the tracking the sans sizes wanted. */
+.pk-heading {
+  font-family: var(--pk-font-serif);
+  font-weight: 500;
+  letter-spacing: 0;
+}