[Feature] Alert, Badge: match shadcn variants, document custom colors

Merged
LE
19d ago
+92-290

Related issue

Related to #597

Description

A proposal: drop the color extras from Alert and Badge so both match shadcn's Base UI + vega variants exactly, and document custom colors through class: instead, as shadcn does.

Today warning and success use one token both as a fill and as text. A bright amber or lime can't do both: in light mode the text is 2.14:1 and 2.38:1 on the card, under the WCAG AA 4.5:1 minimum (#597). Badge's palette colors have the same problem, because text-*-500 on a tinted background fails too (amber 2.15:1, lime 1.98:1, red 3.76:1). Rather than adding a darker --*-text token per color, this PR leaves color choices to the app, where RubyUI's copy-paste model already puts them.

What changes

  • Alert keeps :default and :destructive, as in vega. :warning and :success are removed.

  • Badge keeps :default, :secondary, :destructive, :outline, :ghost and :link, as in vega. :success, :warning and the 22 palette colors (:slate to :rose) are removed. :primary, size: and href: stay.

  • Theme: --warning, --warning-foreground, --success, --success-foreground and their --color-* mappings are gone from the install template, the docs CSS, the installation pages and the theme builder (Theme::CSS no longer needs exclude_ruby_ui_vars). This also removes white-on-warning fills, which failed as well (2.14:1).

  • Docs: Alert and Badge get a "Custom Colors" example with the same classes as shadcn's examples (examples/base/alert-colors.tsx, badge-colors.tsx). Using a light and a dark shade of one scale keeps the text readable in both themes:

    ExampleLightDark
    Alert, amber 900 on 50 / 50 on 9508.77:114.46:1
    Badge, 700 on 50 / 300 on 950 (blue, green, sky, purple, red)4.72–6.60:18.13–10.67:1

    Pages that used the removed variants (home, table, data table, installation, 404, components table, progress) now pass the same kind of classes.

  • TailwindMerge in Base already lets class: replace the variant's colors, so no component code was needed for custom colors. Tests cover this.

Upgrade notes

  • Alert(variant: :warning | :success) and Badge(variant: :success | :warning | :amber | …) don't raise: unknown variants already fall back to :default. Alerts render neutral, and badges render solid primary.

  • To keep a color, pass classes:

    Alert(class: "border-amber-200 bg-amber-50 text-amber-900 dark:border-amber-900 dark:bg-amber-950 dark:text-amber-50 *:data-[slot=alert-description]:text-amber-900/90 dark:*:data-[slot=alert-description]:text-amber-50/90") { ... }
    Badge(class: "bg-green-50 text-green-700 dark:bg-green-950 dark:text-green-300") { "Active" }
    

    Or add the variant back in your app's copy of the component.

  • Apps that already generated Alert or Badge are unaffected until they regenerate them. The old tokens can stay in an app's CSS; nothing in RubyUI reads them anymore.

  • A badge with custom colors and href: still hovers to bg-primary/80 (the default variant's hover). Same as shadcn; add a [a]:hover: class if needed.

This is a breaking change for apps that regenerate these components, so the version bump is the maintainers' call.

Open question

If you'd rather keep Badge's palette colors for now, I can split them out and leave this PR to warning and success only.

Before / After

Before (main, light)After (light)After (dark)
Alertalert-main-lightalert-custom-lightalert-custom-dark
Badgebadge-main-lightbadge-custom-lightbadge-custom-dark

Before is the published rubyui.com (Warning/Success and Status/Other Colors examples). After is the new "Custom Colors" example on this branch.

Audit

/shadcn-audit alert and /shadcn-audit badge against shadcn Base UI + vega at 4aaea19d: no ❌ or ⚠️. Variant sets and class tokens equal vega, HTML and accessibility trees match, and the neutral theme check passes. The two ⏸ lines are the test environment font stack, not the components. The audit ran on a snapshot of this branch (head 978fa07d) with the same content as the commit. This PR also moves audit/component_map/{alert,badge}.yml to that baseline so the weekly drift check starts here.

Checklist
shadcn audit  ruby-ui/ruby_ui
  base ce88825d  head 978fa07d  shadcn 4aaea19d
⚠️ Environment  font: "Inter Variable", "system-ui", -apple-system, "system-ui", "Segoe UI", Roboto, "Helvetica Neue", Arial, "sans-serif" vs "Inter Variable", sans-serif (light)
⚠️ Environment  font: "Inter Variable", "system-ui", -apple-system, "system-ui", "Segoe UI", Roboto, "Helvetica Neue", Arial, "sans-serif" vs "Inter Variable", sans-serif (dark)
✅ Theme  neutral tokens match shadcn
Alert  (ref: bases/base/ui/alert.tsx + style-vega.css @ 4aaea19d)
  ⏸ Look       properties: font-family
               Alert, AlertTitle, AlertDescription, AlertAction — explained by environment diff: font. Kept as is: test environment font stack, not the component; Inter renders on both sides. Done in this PR: `baseline alert 4aaea19d9cff3e0908e12a8c1d504b8c5ec34610`.
  ✅ ARIA       Alert, AlertTitle, AlertDescription, AlertAction: accessibility tree matches
               ↳ accessibility tree (shadcn-audit collect)
  ✅ Look       variants default, destructive: same class tokens
               warning and success removed; the variant set now equals vega.
               ↳ bases/base/ui/alert.tsx
  ✅ HTML       div[data-slot=alert][role=alert] > svg, div[alert-title], div[alert-description], div[alert-action]
               Read from the rendered DOM of both fixtures.
               ↳ bases/base/ui/alert.tsx
  ✅ Props      variant: :default | :destructive
               Removed variants (:warning, :success) fall back to :default; covered by gem tests.
               ↳ bases/base/ui/alert.tsx
  ✅ Native     no JavaScript
               Static component; nothing to replace.
               ↳ gem/lib/ruby_ui/alert/
Badge  (ref: bases/base/ui/badge.tsx + style-vega.css @ 4aaea19d)
  ✅ Look       border-bottom-left-radius: 32px; border-bottom-right-radius: 32px; border-top-left-radius: 32px; border-top-right-radius: 32px
               Badge — closed/light, closed/dark. Override: renders the same. The badge is 20px tall, so both radii clamp to 10px; pixel diff 0 in light and dark. Cause is pre-existing and outside this PR: RubyUI themes define radius-xl as radius+4px and leave 2xl-4xl at Tailwind defaults (4xl = 2rem), while shadcn derives the scale from --radius (4xl = radius*2.6). Done in this PR: `baseline badge 4aaea19d9cff3e0908e12a8c1d504b8c5ec34610`.
               ↳ computed styles (shadcn-audit collect)
  ⏸ Look       properties: font-family
               Badge — explained by environment diff: font. Kept as is: test environment font stack, not the component; Inter renders on both sides.
  ✅ ARIA       Badge: accessibility tree matches
               ↳ accessibility tree (shadcn-audit collect)
  ✅ Look       variants default, secondary, destructive, outline, ghost, link: same class tokens
               success, warning and the 22 palette colors removed; computed bg/color/height match for all 7 fixture badges.
               ↳ bases/base/ui/badge.tsx
  ✅ HTML       span[data-slot=badge][data-variant]; a[href] with href:
               Read from the rendered DOM of both fixtures.
               ↳ bases/base/ui/badge.tsx
  ✅ Props      variant:, href: — intentional
               Phlex has no render prop; a link is the only other element a badge needs, and href: matches Link and PaginationItem. size: is a RubyUI extra (rubyui_only).
               ↳ audit/divergences/badge.yml
  ✅ Native     no JavaScript
               Static component; nothing to replace.
               ↳ gem/lib/ruby_ui/badge/

Testing instructions

  • cd gem && bundle exec rake: 570 runs, 0 failures; standardrb clean.
  • cd docs && bin/rails db:test:prepare test && bundle exec standardrb: 75 runs, 0 failures; standardrb clean.
  • cd mcp && bundle exec exe/ruby-ui-mcp-build: registry rebuilt and committed.
  • cd audit && bundle exec rake: 277 runs, 0 failures.
  • cd docs && bin/dev and check /docs/alert, /docs/badge, /docs/table, /docs/data_table, /docs/progress, /, /themes and the installation pages in light and dark.

🤖 Generated with Claude Code


Summary by cubic

Matches Alert and Badge variants to shadcn exactly by dropping the RubyUI color extras (Alert's warning/success, Badge's success/warning plus 22 palette colors), which used one token as both fill and text and failed WCAG AA contrast on light backgrounds. Custom colors are now documented through class: with paired light/dark shades, following shadcn's own copy-paste model.

Changes

  • Alert keeps :default and :destructive; Badge keeps the seven shadcn variants plus the :primary alias and size:/href:.
  • The --warning and --success theme tokens are removed from the install template, docs CSS, and theme builder, and Theme::CSS no longer filters RubyUI-specific vars.
  • Docs and the MCP registry now show "Custom Colors" examples plus migrated usages across Table, DataTable, home, 404, progress, and installation pages.
  • The amber custom-color alerts tint the description text like vega's destructive variant, keeping it readable on the tinted background.
  • The shadcn audit baselines for Alert and Badge are updated, and tests cover fallback and class-override behavior.

Migration

  • Removed variants don't raise; they fall back to :default, so Alerts render neutral and Badges render solid primary.
  • Apps that regenerate Alert or Badge lose the color variants; pass class: or re-add the variant in your app's copy.
  • Old tokens can stay in an app's CSS; nothing in RubyUI reads them anymore.