[Feature] Alert, Badge: match shadcn variants, document custom colors
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
:defaultand:destructive, as in vega.:warningand:successare removed. -
Badge keeps
:default,:secondary,:destructive,:outline,:ghostand:link, as in vega.:success,:warningand the 22 palette colors (:slateto:rose) are removed.:primary,size:andhref:stay. -
Theme:
--warning,--warning-foreground,--success,--success-foregroundand their--color-*mappings are gone from the install template, the docs CSS, the installation pages and the theme builder (Theme::CSSno longer needsexclude_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:Example Light Dark Alert, amber 900 on 50 / 50 on 950 8.77:1 14.46:1 Badge, 700 on 50 / 300 on 950 (blue, green, sky, purple, red) 4.72–6.60:1 8.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.
-
TailwindMergeinBasealready letsclass:replace the variant's colors, so no component code was needed for custom colors. Tests cover this.
Upgrade notes
-
Alert(variant: :warning | :success)andBadge(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 tobg-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) | |
|---|---|---|---|
| Alert | |||
| Badge |
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/devand check/docs/alert,/docs/badge,/docs/table,/docs/data_table,/docs/progress,/,/themesand 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
:defaultand:destructive; Badge keeps the seven shadcn variants plus the:primaryalias andsize:/href:. - The
--warningand--successtheme tokens are removed from the install template, docs CSS, and theme builder, andTheme::CSSno 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.