@twoux/ui 0.0.0-stage → 0.1.1

package/SHADCN-DIFF.md

@@ -0,0 +1,228 @@
+# How TwoUX differs from shadcn/ui
+
+Generated by `scripts/tailor-shadcn.mjs`. Each component starts from the untouched shadcn source in `packages/ui/src/shadcn/`.
+
+## Every component
+
+- Import paths point at TwoUX
+- dark: classes removed: the dark theme comes from the role tokens (light-dark()), so components need no dark variants
+- Type mapped to TwoUX's compact scale (shadcn text-xs/sm/base = 12/14/16px → TwoUX text-sm/base/md = 12/13/14px)
+- Arbitrary radii replaced with tokens
+- Every state change eases (colour, background, border and ring, 120ms ease-out); shadcn only animates colour and ring, so borders snapped
+- Menu and palette items fade their highlight in and out (120ms) instead of snapping
+- Invalid fields get a softer red edge; the message carries the error
+- While someone types into an invalid field it shows the normal focus edge, not red: the message below still names the error
+- Overlays: TwoUX's scrim, which works in light and dark. shadcn's own motion (timing, easing, 95% zoom) is kept as it is
+- Dialogs: 16px corners, the soft edge, TwoUX's floating shadow and 20px padding
+- Tighter corners: 6px (sm) for buttons, fields and cards, 4px (xs) for what sits inside them, 8px (md) for popovers, menus and dialogs. Every shadcn radius moves one step down
+- Corners follow the role, not shadcn's class: menus and the command palette are overlays (8px); empty-state frames and media tiles are cards (6px)
+
+## button
+
+- Compact heights: 32px default, 28px sm, 24px xs, 36px lg
+- Primary gets a hairline shadow so it sits on grey and white alike
+- Outline uses the light input edge and darkens it on hover
+- Adds warning: risky but reversible actions (from Geist)
+- Icons 14px beside 13px text, so they support the label instead of outweighing it
+- Button corners come from theme.json (radius.button: a px value or "pill"), so buttons can be rounder than fields without touching the component
+- Tactile press
+- Adds loading (spinner, aria-busy, stays focusable) and shortcut (Kbd after the label)
+- The shortcut works, not just shows: inside ShortcutsProvider, typing it presses the button (single keys obey the off setting, WCAG 2.1.4)
+
+## badge
+
+- Status badges are small soft pills, square-ish to read as labels, not buttons
+- Soft tones: the word carries the meaning, colour repeats it (WCAG 1.4.1)
+- Adds dot: a leading dot for scanning long columns
+
+## kbd
+
+- Inside a primary or destructive button, the key sits on a darker tint so white text keeps 4.5:1
+
+## checkbox
+
+- Edge at 3.59:1: nothing else identifies a checkbox (WCAG 1.4.11)
+- Invisible 26px hit area (WCAG 2.5.8)
+- The tick scales in instead of appearing
+- Indeterminate (some rows selected) shows an indigo box with a minus, not a tick on an empty box
+
+## radio-group
+
+- Edge at 3.59:1 (WCAG 1.4.11)
+- Invisible 26px hit area (WCAG 2.5.8)
+- Compact rows
+- The dot scales in instead of appearing
+
+## switch
+
+- Thumb glides with TwoUX's ease-out
+- Off track at 3.59:1 so the switch is visible when off (WCAG 1.4.11)
+- Invisible hit area: 28px around the 16px track (WCAG 2.5.8)
+- Sized to its label: a 16×28 track by default (14×24 small), no taller than the 15px text beside it, with 2px of track around the thumb
+- Thumb travels the full track at each size
+
+## tabs
+
+- Inactive tabs use secondary text (9:1), not 60% ink, which is 4.46:1 on the tab rail
+- TwoUX's default is the underline (line) style for page sections
+- Line tabs span the width with a divider underneath
+- Line tabs: no padding, indigo text and underline when active
+- Adds count after the label; it pops when it changes
+- One indicator slides to the active tab (underline or pill) instead of jumping; vertical tabs keep per-tab styling
+
+## toggle
+
+- Compact heights
+- On reads as chosen, not hovered: indigo tint and text, which stay while the pointer is over it
+- Icons 14px, in proportion with 13px text
+- Outline: light edge that darkens on hover, indigo edge when on
+
+## toggle-group
+
+- Shared changes only
+
+## tooltip
+
+- Short delay so moving across a toolbar does not flash labels
+- Keeps a gap from the trigger and stays inside the window
+- Compact padding
+
+## input
+
+- Compact 32px, light edge that darkens on hover
+- One size on every screen
+
+## input-group
+
+- Compact 32px
+- Light edge darkens on hover
+
+## textarea
+
+- Shared changes only
+
+## label
+
+- Shared changes only
+
+## separator
+
+- Shared changes only
+
+## field
+
+- TwoUX spacing between fields is tighter (compact density)
+- An invalid field keeps its label and value in normal text; only the edge and the message turn red (less alarming, still clear)
+
+## dropdown-menu
+
+- Shortcut slot holds keys; no letter-spacing so Kbd groups read cleanly
+- Icons stay smaller than the 13px label and muted
+- Check and radio marks sit at the end of the item, so every label in a menu starts at the same edge
+- Group headings are smaller and muted, so they read as headings, not as items people can choose
+
+## dialog
+
+- Shared changes only
+
+## breadcrumb
+
+- One line in the top bar: never wraps; the current page truncates last and reads darker
+- Separator chevrons are small and muted
+
+## avatar
+
+- 22px by default (18px small, 32px large); initials 11px semibold in white on a per-person colour
+- Stacks overlap by 6px with a 2px white ring
+
+## sheet
+
+- Panels are 440px on the right (full width on phones), slide with TwoUX's motion, and float with the overlay shadow
+- Motion from shadcn's Base UI sheet: a 40px slide with a fade, 200ms ease-in-out both ways (the full-width 500ms slide felt heavy)
+
+## popover
+
+- Floats like every overlay: 8px corners, light edge, the floating shadow, 12px padding
+- Never cut off: keeps 8px from the viewport edge and flips when there is no room
+
+## collapsible
+
+- Shared changes only
+
+## button-group
+
+- Text segment on the quiet surface with the light edge, 12px padding and 14px icons, in proportion with compact buttons
+- The divider between two filled buttons uses the primary-on-primary edge, so a split primary button reads as one control with two parts
+
+## select
+
+- Compact heights (32px, 28px small), field edge with hover, white fill, 14px chevron
+- The list floats: 8px corners, light edge, floating shadow
+
+## table
+
+- Adds containerClassName, so a table can scroll inside a fixed height and keep its header sticky
+- Adds size="dense": 28px rows and header with 8px padding, the same 13px text, for spreadsheet-like data (inventories, ledgers, imports, mapping). Not a density setting
+- Sticky header on the quiet surface, with the light divider
+- Rows: light divider, hover fill, indigo tint when selected, an indigo edge on the keyboard-focused row
+- Rows and header use the row tokens (36px, or 28px dense), 12px side padding and 2px top and bottom, so a 28px control in a cell keeps the row at 36px; header labels 12px medium grey, in sentence case
+- Frozen columns: data-pinned on a head and its cells keeps them in view when the table scrolls sideways, at left var(--pin); data-pinned="last" draws the edge
+
+## card
+
+- Compact card: 16px padding and gaps, light edge, 6px corners, the resting card shadow
+- Title 14px semibold, description in readable grey
+- Optional level makes the title a heading, for cards that hold a page section
+- Adds CardFooter band: a tinted strip across the bottom for a secondary line (as in Clerk's “Already have an account?”)
+
+## alert
+
+- Compact banner: 8px corners, 14px icon, room for one action on the right
+- Information is neutral grey, not blue: colour is kept for problems
+- Errors: soft red fill and edge, dark text; adds warning
+- Only errors interrupt a screen reader (role alert); information and warnings are polite (role status)
+- Title wraps instead of being cut to one line
+- Adds AlertAction: Dismiss (ghost) then one action, on the right
+
+## alert-dialog
+
+- Confirmations are 420px wide at most
+- Body text readable at 6:1, not the muted grey
+- Smaller media tile
+
+## skeleton
+
+- Shimmer at 1.4s instead of a pulse, on TwoUX's hover grey; stops with reduced motion
+
+## empty
+
+- Dashed container sized to the region it replaces, compact spacing
+- 32px neutral icon tile, no illustration; adds the error tile for the error state
+- The title is a real heading for screen readers (level 2 by default, set level to fit the page)
+- Description at most 36 characters wide, readable grey
+
+## sonner
+
+- Theme from TwoUX's <html data-theme> (light by default), not next-themes
+- Status icons 14px in their status colour
+- TwoUX defaults: bottom right, 16px from the edges, one at a time, 6 seconds, 340px wide; Undo is a quiet text button
+- Solid surface: shadcn points at --popover and --border, which TwoUX names --color-popover and --color-line, so the toast was see-through
+- Anti-collision: the toast rises above the focused element and anything marked data-toast-avoid (such as a sticky footer), so it never hides them (WCAG 2.4.11)
+
+## calendar
+
+- UK English by default: en-GB month and weekday names, weeks start on Monday
+- Month buttons named in plain words: Previous month, Next month
+- Weekday and week-number labels on TwoUX's 12px muted text, not an arbitrary 0.8rem
+- Today gets a ring, not a fill, so it never looks selected; the day's name also says Today
+- Days inside a range use the selection fill, as selected rows do
+- Parts kept between renders: shadcn creates Root, Chevron and WeekNumber afresh each render, so any state change remounted the grid and a click that started on one day button ended on a new one and was lost
+
+## command
+
+- Icons stay smaller than the label and muted
+- Group labels in sentence case, quiet
+- Dialog keeps compact rows and 14px icons; shadcn enlarges them to 20px with 12px padding
+- Shortcut slot holds words as well as keys: no letter-spacing, icons align
+- Adds commandProps (shouldFilter, loop…) passed to the inner Command
+- Opens near the top like a search, with the floating shadow; Esc closes it so no close button