@journ/bloom 0.1.1

package/DESIGN.md

@@ -0,0 +1,287 @@
+# Bloom design system
+
+The design system that `@journ/bloom` implements: token-driven, React 19 and Tailwind v4. It has the same components and API as `@journ/lotus`, with tokens named `bloom-`, and a look inspired by Midday's UI. Behavior, state and accessibility come from `@journ/nude`; everything below is about how things look and move.
+
+The rules marked as enforced are checked by `tools/check-design.ts`, which runs with `pnpm lint`. See [Enforced rules](#enforced-rules).
+
+## Design style
+
+Dark-first, monochrome, flat. A near-black canvas, hairline borders in place of fills, square corners, one sans face, and monospace for numbers and status labels. Color appears only as status.
+
+### Color
+
+Never use raw colors or Tailwind palette colors in components (enforced). Tokens live in `src/styles/tokens.css`.
+
+**Palette tokens** are the same in both themes. They are status colors, used as washes far more than as fills:
+
+| Token          | Role                                            |
+| -------------- | ----------------------------------------------- |
+| `bloom-ink`    | The `ink` tone: always dark                     |
+| `bloom-paper`  | Text on `ink` and on the coral and indigo fills |
+| `bloom-coral`  | Destructive actions, errors, invalid fields     |
+| `bloom-yellow` | Warnings, overdue                               |
+| `bloom-indigo` | A second informational color                    |
+| `bloom-mint`   | Success, paid, complete                         |
+| `bloom-sky`    | The focus ring, informational labels            |
+
+**Role tokens** come in a light/dark pair, `bloom-<role>` and `bloom-<role>-dark`:
+
+| Role         | Used for                                                  |
+| ------------ | --------------------------------------------------------- |
+| `canvas`     | Page background, the modal backdrop, the switch thumb     |
+| `surface`    | Cards, sheets, drawers, toasts, menus                     |
+| `foreground` | Text and icons on the canvas and on surfaces              |
+| `line`       | Every hairline: card edges, field outlines                |
+| `accent`     | Accent text on a surface (amber in light, yellow in dark) |
+
+Rules:
+
+- Blocks are separated by a 1px border, not by a fill: `surface` has the same value as `canvas` in both themes. `surface` and `raised` in `src/lib/theme.ts` carry the border.
+- Fields, selects and picker triggers have no fill: `control` is a transparent box with a hairline outline.
+- Selected, hovered and highlighted states are a wash of the text color (`bg-current/8`, the `dim` pair), never a color. Tabs and toggles sit in a dim track and the selected one takes the canvas color; the current nav item gets a hairline edge.
+- A colored tone on a card, alert, dialog or page is a 10% wash with the edge in the color (`surfaceTones`, `pageTints` in `src/lib/tones.ts`); the text stays `foreground`. Status labels (`Badge`, `Chip`) use `labelTones`: a wash, with the color as text in dark.
+- Solid color is for buttons only (`solidTones`). The primary button is `neutral`, which inverts with the theme.
+- Secondary text is the same color at reduced opacity (`opacity-60`), never a separate gray.
+
+### Themes
+
+Components follow Tailwind's `dark:` variant. The package defines it in `tokens.css` so it works both ways:
+
+- With no class it follows the OS (`prefers-color-scheme`).
+- `.dark` on `<html>` (or any ancestor) forces dark, `.light` forces light. Themes can nest.
+
+The package has no switcher. The playground's `ThemeToggle` (`apps/playground/src/bloom/demos/theme-toggle.tsx`) is the reference: a system/light/dark `ToggleGroup` that sets the class on `<html>` and remembers the choice. Portals render on `<body>`, so the class must be on `<html>`.
+
+- Every light/dark pairing is written once in `src/lib/theme.ts` (`canvas`, `surface`, `raised`, `control`, `neutral`, `dim`, `line`, `scrim`, `foreground`, `accentText`). Components import these; do not write `dark:` pairs inline (enforced).
+- To restyle a theme, override the role tokens in your app's `@theme`, for example `--color-bloom-surface-dark`. Light and dark are independent.
+- To follow only a class (never the OS), redefine the variant in your app: `@custom-variant dark (&:where(.dark, .dark *));`.
+
+### Shape
+
+- Corners are square. `--radius-bloom` is `0`; buttons, fields, cards, sheets and toasts use `rounded-bloom`, so one token rounds them all.
+- Round is reserved for what is round in Midday: `Badge`, avatars, radios, the switch, the slider, calendar days, carousel arrows and message bubbles. `Chip` is a square tag. The drawer has a rounded top (`rounded-t-xl`).
+- Sheets float from `md` up: inset from the viewport edge, bordered on all sides.
+
+### Typography
+
+- One face, `font-bloom-display` (Hedvig Letters Sans, weight 400 and 500). `canvas` and `surfaceFill` set it, so pages and portaled overlays both get it. Titles are sentence case, `font-medium`, never uppercase.
+- Numbers that carry meaning (stat values, OTP) and status labels (badges, chips) are `font-mono`.
+- Body is small (`text-sm/5`, `text-sm/6`).
+- Inputs are 16px on mobile and 14px from `sm` up, to prevent iOS focus zoom.
+
+### Layout
+
+- Every screen is a `Page.Root` with its own `tone`. Each page can pick a different background, as in the references. `canvas` is the default and follows the theme; the colored tones wash the canvas and keep its text.
+- Controls that must adapt to the page (`IconButton` and `Button` with `ghost` or `outline`, `Composer`) inherit the page text color and use `currentColor` for their tint, so they stay legible on any page tone. Cards keep their own tone and do not depend on the page.
+- `Page.Content` is the column (safe-area padding included). `Page.Footer` pins its content, usually the `NavBar`, to the bottom.
+- Single column, content width capped at `max-w-sm`, `px-4` gutters.
+- Page structure: `Page.Root` > `Page.Content` > `PageHeader` (back button, title, actions), optional filter row of `PillSelect`, a stack of cards, `NavBar` inside `Page.Footer`.
+- Spacing between blocks is `gap-4`. Inside cards, `gap-3`.
+- Icons come from `lucide-react`, sized by the parent (`size-5`, `size-4` in small buttons).
+
+### Interaction
+
+Every pressable thing shares `src/lib/interactive.ts`:
+
+- Keyboard-only focus ring (`focus-visible`), never on tap.
+- Hover and press overlay using `currentColor` (`/10` hover, `/15` press), layered between background and content.
+- Disabled and `aria-disabled` dim to 50% and ignore pointer events.
+- `TouchTarget` expands the hit area to at least 44x44px on touch devices only.
+
+Use `Button`, `IconButton` or `NavBar.Item` for anything pressable. Do not hand-roll pressable elements.
+
+### Shared building blocks
+
+Before writing a class string or an animation, look in `src/lib` first:
+
+- `theme.ts`: every light/dark pairing written with `dark:`.
+- `tones.ts`: `fills`, `solidTones`, `labelTones`, `inkTone`, `surfaceTones`, `pageTints`. Every tone map is built from these.
+- `text-styles.ts`: `displayTitle`, `displayHeading`, `displayLabel`, `mutedText`, `controlSize`, `fieldText`, `fieldRing` and the `selectedWhen*` classes.
+- `overlay.ts`: floating surface/item/card styles, the modal overlay and the centered panel (Dialog, AlertDialog).
+- `modal-content.tsx`: `ModalContent` gives a nude modal content (Dialog, AlertDialog, Sheet) its fading overlay and animated panel.
+- `menu-parts.tsx`: `styleMenuParts(parts)` styles the nude `Content`, `Item`, `Label` and `Separator` of a menu. Used by DropdownMenu and ContextMenu.
+- `picker.tsx`: `stylePicker(parts)` styles a nude picker's `Trigger` and `Value`. Used by Combobox, DatePicker, DateRangePicker and MultipleSelector.
+- `step-button.tsx`: `stepButton(Icon, style)` gives the ghost icon button look to a nude previous, next, minus or plus part (Calendar, Carousel, MonthStepper, QuantityInput).
+- `button.tsx`, `input.tsx`, `composer.tsx`, `combobox-parts.tsx`: besides the component, each exports its class builder (`button`, `input`, `composerRoot`, `composerInput`, `option`) for parts that bind a nude element to their own state.
+- `icon-tile.ts`: the bordered icon square used by Card.Icon, EmptyState.Icon and FileDropzone.Icon.
+- `interactive.ts`: `interactive` and `pressReset` for anything pressable.
+- `use-enter.ts`: `useEnter`, `usePopEnter`, `useDropEnter` and `useExpand`.
+- `touch-target.tsx`: the 44px touch area, never re-implement it with classes.
+
+State and parsing helpers are not here: `useControllableState`, `useDraft`, `createRequiredContext` and `prefersReducedMotion` live in `@journ/lift`; `clamp`, the number, date, month and time helpers in `@journ/fitter-happier`.
+
+### Scrollbars
+
+- Native scroll containers inside bloom use the `scrollbar-bloom` utility (enforced) (defined in `tokens.css`): thin, transparent track, thumb in the current text color at 30%.
+- For a fully custom, overlay scrollbar use `ScrollArea` (Radix). It shows on hover by default and has a 44px touch hit area.
+
+### Motion and touch
+
+Rules from the design style guide, applied across the package:
+
+- Interactions stay at or under 200ms. Frequent surfaces (menus, popovers, tooltips) are quiet: small scale, short fade.
+- Dialogs scale in from 0.97 in 100ms. Nothing moves on press. Never animate from 0.
+- Animate `transform` and `opacity` only. Skip animation when `prefers-reduced-motion` is set.
+- Pressable controls share `interactive`/`pressReset` from `src/lib/interactive.ts`: no text selection, no iOS tap flash, keyboard-only focus ring.
+- Numbers that change or line up (stats, table cells, badges, pagination, calendar days) use `tabular-nums`.
+- Inputs are 16px on mobile. Hover styles come from Tailwind, which already gates them behind `(hover: hover)`.
+- Focus rings use `outline` with an offset. Modern browsers round it to the element radius, so we do not use `box-shadow` rings (enforced).
+
+## Composition rules
+
+Follow the composable pattern (`folio kb get react-composition-patterns`).
+
+- Compound components: `Card.Root`, `Card.Header`, `Card.Title`. Consumers pick the parts they need.
+- Pass `children`, not `renderX` props. No boolean props like `showFooter`.
+- Variants are string unions (`tone`, `from`), never combinations of booleans.
+- Each part sets a `data-slot` attribute and merges `className` through `cn`, so consumers can override.
+- React 19 style: `ref` is a regular prop, no `forwardRef`.
+- Share state through a provider only when parts truly share state. Stateless parts need no context.
+- Shared context is `{ state, actions, meta }`. `X.Provider` takes all three, so the state can come from anywhere (local, global store, server). `X.Root` is the default provider that owns local state with `value`, `defaultValue` and `onValueChange`. Neither renders DOM; `X.Frame` does.
+- Export a `useX` hook next to the namespace, so custom UI inside the provider can read state and call actions without being nested in the frame.
+
+## Code conventions
+
+- Every component wraps the `@journ/nude` part of the same name and merges `className` through `cn` or a `tv` recipe. Never import Radix, vaul, cmdk, sonner, Embla, TanStack Table or react-markdown here; they belong to nude. (enforced)
+- Inner elements that nude renders are styled through its `classNames` prop. Composites take bloom components through nude's `components` prop.
+- Icons (`lucide-react`), the touch target and the spinner are passed as children.
+- Components are arrow functions.
+- Export only at the end of the file, in one `export { ... }` block, so unused code is easy to spot.
+- A compound object (`const Card = { Root, ... }`) is the public API of a component file.
+- Client-only parts live in `*-parts.tsx` with `'use client'`. The sibling file without the directive builds the `Drawer.X` or `Toast.X` object, because a namespace object exported from a client file cannot be read from a server component.
+- Tests only for components with real logic or state (switchers, accordions, slides, `Stack`). Stateless presentational components are not tested. Run with `pnpm nx test @journ/bloom`; `animejs` is mocked.
+
+## Enforced rules
+
+`tools/check-design.ts` reads every class string in `src` (tests excluded) and fails `pnpm lint` on:
+
+| Rule      | What fails                                                                                                                                                           |
+| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `color`   | A Tailwind palette color (`bg-red-500`, `text-white`) or a raw value (`bg-[#fff]`, `text-[oklch(...)]`). Use `bloom-*` tokens, `current`, `transparent` or `inherit` |
+| `dark`    | A `dark:` variant outside `src/lib`. Light and dark pairings are written once, in `src/lib/theme.ts`                                                                 |
+| `font`    | A font family other than `font-bloom-display` and `font-mono`                                                                                                        |
+| `focus`   | A `ring` utility under a focus variant. Focus uses `outline` with an offset                                                                                          |
+| `scroll`  | `overflow-auto`, `overflow-x-auto`, `overflow-y-auto` or the `scroll` forms without `scrollbar-bloom` in the same class string                                       |
+| `spacing` | An arbitrary gap, padding or margin (`gap-[13px]`) or `space-x`/`space-y`. Use the scale and `gap`. Safe-area `env()` values are allowed                             |
+| `radius`  | An arbitrary radius. Use `rounded-bloom`, `rounded-full` or the scale; `rounded-[inherit]` is allowed                                                                |
+| `import`  | A direct import of a library that belongs to nude                                                                                                                    |
+
+The check cannot judge intent, so these stay review rules: `gap-4` between blocks and `gap-3` inside cards, `bloom-ink` text on colored fills, `tabular-nums` on numbers, the 200ms motion budget, and using `Button`, `IconButton` or `NavBar.Item` for anything pressable.
+
+## Theming
+
+Import the tokens, then override any of them in your own `@theme` block after it:
+
+```css
+@import 'tailwindcss';
+@import '@journ/bloom/tokens.css';
+@source '../node_modules/@journ/bloom/dist';
+
+@theme {
+	--color-bloom-coral: oklch(65% 0.2 20);
+	--radius-bloom: 1rem;
+}
+```
+
+Alternatively `import '@journ/bloom/styles.css'` loads the precompiled stylesheet, tokens included, and the app needs no Tailwind. The tokens cannot be overridden through `@theme` that way; override the CSS variables (`--color-bloom-coral`) instead.
+
+The typeface is `--font-bloom-display`. Load Hedvig Letters Sans (or your own face) and set that variable. In Next.js, `next/font` with `variable: '--font-bloom-display'` does it.
+
+## Components
+
+Import from `@journ/bloom` or per file (`@journ/bloom/card`). The library named in parentheses is what the nude part is built on.
+
+| Component                       | Parts                                                                                                                                                                                 |
+| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `Accordion` (Radix, animejs)    | `Root` (`type`), `Item`, `Trigger`, `Content`                                                                                                                                         |
+| `AlertDialog` (Radix)           | `Root`, `Trigger`, `Content` (`tone`), `Title`, `Description`, `Actions`, `Cancel`, `Action`                                                                                          |
+| `Alert`                         | `Root` (`tone`), `Icon`, `Body`, `Title`, `Description`, `Actions`                                                                                                                    |
+| `AnimatedSize` (animejs)        | single element, `width`, `height`. Glides to its content's size                                                                                                                       |
+| `Avatar` (Radix)                | `Root`, `Image`, `Fallback`                                                                                                                                                           |
+| `Badge`                         | single element, `tone`                                                                                                                                                                |
+| `Breadcrumbs`                   | `Root`, `List`, `Item`, `Link`, `Page`, `Separator`                                                                                                                                   |
+| `BulkBar`                       | `Root`, `Count`, `Actions`                                                                                                                                                            |
+| `Button`                        | single element, `tone`, `pending`, renders `<a>` with `href`                                                                                                                          |
+| `Calendar`                      | `Provider`, `Root`, `Frame`, `Header`, `Heading`, `Previous`, `Next`, `Weekdays`, `Days`, `Months`, `Years`, `useCalendar`                                                            |
+| `Card`                          | `Root` (`tone`), `Icon`, `Header`, `Title`, `Description`, `Content`, `Footer`                                                                                                        |
+| `Checkbox` (Radix)              | `Root` (supports `checked="indeterminate"`), `Indicator`                                                                                                                              |
+| `Carousel` (Embla)              | `Root` (`opts`, `orientation`), `Content`, `Item`, `Previous`, `Next`                                                                                                                 |
+| `Chip`                          | `Root` (`tone`), `Dot`, `Remove`, `Tag`                                                                                                                                               |
+| `Collapsible` (Radix, animejs)  | `Root`, `Trigger`, `Content`                                                                                                                                                          |
+| `ContextMenu` (Radix)           | `Root`, `Trigger`, `Content`, `Group`, `Label`, `Item`, `Separator`                                                                                                                   |
+| `Combobox` (cmdk)               | `Provider`, `Root`, `Trigger`, `Value`, `Content`, `Title`, `Description`, `Frame`, `Input`, `List`, `Empty`, `Group`, `Item`, `ItemIndicator`, `useCombobox`                         |
+| `CommandPalette` (cmdk, Radix)  | `Root` (`onSelect`, `shortcut`), `Trigger`, `Content`, plus the Combobox list parts `Frame`, `Input`, `List`, `Empty`, `Group`, `Item`, `ItemIndicator`                               |
+| `Composer`                      | `Root`, `Input`                                                                                                                                                                       |
+| `DatePicker`                    | `Provider`, `Root`, `Trigger`, `Value`, `Content`, `Title`, `Description`, `Calendar` (wraps `Calendar.Root`), `useDatePicker`                                                        |
+| `DescriptionList`               | `Root`, `Term`, `Details`                                                                                                                                                             |
+| `DateRangePicker`               | `Root` (`value`, `locale`), `Trigger`, `Value`, `Content`, `Title`, `Description`, `Calendar`. Two clicks make a range                                                                |
+| `CurrencyInput`                 | `Root` (`value`, `currency`, `locale`, `min`, `max`), `Field`                                                                                                                         |
+| `DataTable` (TanStack Table v9) | `Root` (`data`, `columns`, `pageSize`, `onSelectionChange`), `Toolbar`, `ColumnPicker`, `Table`, `Pager`, `SelectionBar`. Helpers: `dataTableColumns`, `selectColumn`, `useDataTable` |
+| `DateInput`                     | `Root` (`value`, `locale`), `Field`. Parses typed dates in the locale's order                                                                                                         |
+| `Dialog` (Radix)                | `Root`, `Trigger`, `Close`, `Content` (`tone`), `Title`, `Description`, `Body`, `Actions`                                                                                             |
+| `FileDropzone`                  | `Root` (`accept`, `maxSize`, `multiple`, `onFilesAccepted`, `onFilesRejected`), `Icon`, `Title`, `Description`                                                                        |
+| `Divider` (Radix)               | single element, `orientation`                                                                                                                                                         |
+| `Drawer` (vaul)                 | `Root`, `Trigger`, `Close`, `Content`, `Title`, `Description`, `Body`, `Actions`                                                                                                      |
+| `DropdownMenu` (Radix)          | `Root`, `Trigger`, `Content`, `Group`, `Label`, `Item`, `Separator`                                                                                                                   |
+| `EmptyState`                    | `Root`, `Icon`, `Title`, `Description`, `Actions`                                                                                                                                     |
+| `Field` (Radix)                 | `Root` (`invalid`), `Label`, `Control`, `Description`, `Error`                                                                                                                        |
+| `Heading`                       | single element, `level` (outline) and `size` (look)                                                                                                                                   |
+| `Icon`                          | sizes any svg child, `size`                                                                                                                                                           |
+| `HoverCard` (Radix)             | `Root`, `Trigger`, `Content`                                                                                                                                                          |
+| `IconButton`                    | single element, `tone`, `size`                                                                                                                                                        |
+| `Input`                         | single element, native `<input>`                                                                                                                                                      |
+| `Link`                          | single element, `asChild` styles a router link                                                                                                                                        |
+| `Markdown` (react-markdown)     | single element, `components` overrides                                                                                                                                                |
+| `MonthStepper`                  | `Root` (`value`, `locale`), `Previous`, `Label`, `Next`                                                                                                                               |
+| `Message`                       | `Root` (`from`), `Bubble`, `Highlight`                                                                                                                                                |
+| `NavBar`                        | `Root`, `Item` (`aria-current="page"` marks active)                                                                                                                                   |
+| `OtpInput` (Radix)              | `Root`, `Slot` (one per character), `Hidden`                                                                                                                                          |
+| `MultipleSelector` (cmdk)       | `Root` (`value`, `fixed`, `max`), `Trigger`, `Value`, `Tags`, `Content`, then Combobox's `Frame`, `Input`, `List`, `Empty`, `Group`, `Item`, `ItemIndicator`, plus `Create`           |
+| `NavigationMenu` (Radix)        | `Root` (includes the viewport), `List`, `Item`, `Trigger`, `Content`, `Link`                                                                                                          |
+| `Page`                          | `Root` (`tone`), `Content`, `Footer`                                                                                                                                                  |
+| `MonthPicker`                   | `Root` (`value`, `locale`), then the Calendar parts `Frame`, `Header`, `Heading`, `Previous`, `Next`, `Months`, `Years`                                                               |
+| `PageHeader`                    | `Root`, `Title`, `Actions`                                                                                                                                                            |
+| `Pagination`                    | `Root`, `Previous`, `List`, `Page`, `Gap`, `Next`                                                                                                                                     |
+| `PillSelect`                    | single element, native `<select>`                                                                                                                                                     |
+| `Popover` (Radix)               | `Root`, `Trigger`, `Content`, `Close`                                                                                                                                                 |
+| `Portal`                        | single element, `container`. Renders children outside the tree (copied from midday). Radix overlays already portal themselves                                                         |
+| `Progress` (Radix)              | `Root` (`value`, `max`), `Indicator` (`tone`)                                                                                                                                         |
+| `Radio` (Radix)                 | `Group`, `Item`                                                                                                                                                                       |
+| `ScrollArea` (Radix)            | `Root` (`type`), `Viewport`, `Scrollbar` (`orientation`), `Corner`                                                                                                                    |
+| `QuantityInput`                 | `Root` (`value`, `min`, `max`, `step`), `Decrement`, `Field`, `Increment`                                                                                                             |
+| `Select` (Radix)                | `Root`, `Trigger`, `Value`, `Content`, `Group`, `Label`, `Item`, `Separator`                                                                                                          |
+| `Sidebar`                       | `Layout`, `Root`, `Header`, `Body`, `Section`, `Heading`, `Item`, `Footer`, `Content` (desktop only)                                                                                  |
+| `Skeleton`                      | single element                                                                                                                                                                        |
+| `Spinner`                       | single element                                                                                                                                                                        |
+| `Stepper`                       | `Root` (`value`), `Item` (`step`), `Indicator`, `Label`, `Description`                                                                                                                |
+| `Sheet` (Radix)                 | `Root`, `Trigger`, `Close`, `Content` (`side`: right, left, top, bottom), `Title`, `Description`, `Body`, `Actions`                                                                   |
+| `Slider` (Radix)                | `Root`, `Track`, `Range`, `Thumb` (one per value)                                                                                                                                     |
+| `Stack` (animejs)               | `Root` (`defaultValue`), `Item` (`value`, `tone`), `Trigger`, `Content`                                                                                                               |
+| `Stat`                          | `Root`, `Label`, `Value`, `Hint`                                                                                                                                                      |
+| `Switch` (Radix)                | `Root`, `Thumb`                                                                                                                                                                       |
+| `Table`                         | `Root`, `Caption`, `Head`, `Body`, `Row`, `Header`, `Cell`                                                                                                                            |
+| `TagInput`                      | `Root` (`validate`), `Tags`, `Tag`, `Field`. Enter or comma adds, Backspace removes, paste splits                                                                                     |
+| `Tabs` (Radix)                  | `Root`, `List`, `Trigger`, `Content`                                                                                                                                                  |
+| `Text`                          | single element, `size`, `tone`                                                                                                                                                        |
+| `Textarea`                      | single element, native `<textarea>`                                                                                                                                                   |
+| `ToggleGroup` (Radix)           | `Root` (`type`), `Item`                                                                                                                                                               |
+| `TextMorph` (animejs)           | single element, `as`. Only changed characters animate                                                                                                                                 |
+| `TextShimmer`                   | single element, `as`. Loading text, CSS only                                                                                                                                          |
+| `TimeRange`                     | `Root` (`value` as `{ start, stop }`), `Start`, `Stop`, `Duration`                                                                                                                    |
+| `Toast` (sonner)                | `Provider`, `show`, `Root`, `Title`, `Description`, `Action`                                                                                                                          |
+| `Tooltip` (Radix)               | `Root` (includes its provider), `Trigger`, `Content`, `Provider`                                                                                                                      |
+
+Card tones: `surface` (default, follows the theme), `coral`, `yellow`, `indigo`, `mint`, `sky`.
+
+Page tones: `canvas` (default, follows the theme), `ink` (always dark), `indigo`, `mint`, `sky`, `yellow`, `coral`.
+
+Button, IconButton and Badge tones: `neutral` (default, inverts with the theme), `coral`, `yellow`, `ink`, and for Button also `field`, `ghost` and `outline`. IconButton has `ghost` (bare, a wash on hover) and `outline` (hairline edge); `outline` is the one addition to the lotus API. `field` is the outlined form-control look used by the select and picker triggers. Use it for any trigger that reads as a field, such as a "Search" bar that opens the command palette.
+
+## Adding a component
+
+1. Build the behavior in `@journ/nude` first: `packages/nude/src/<name>.tsx` as a compound object of unstyled parts with `data-slot`.
+2. Create `packages/bloom/src/<name>.tsx`: wrap each nude part and add classes through `cn` or `tv`.
+3. Use only `bloom-*` tokens. Add a token before adding a raw value.
+4. Reuse `interactive` and `TouchTarget` for anything pressable.
+5. Export at the end of the file, then add it to `src/index.ts`. Any `src/*.tsx` is also exposed as `@journ/bloom/<name>`.
+6. Add a usage to a story in `apps/playground/src` and check it on a phone-width viewport.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Journ
+
+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.

package/README.md

@@ -0,0 +1,59 @@
+# @journ/bloom
+
+Styled UI library A. Wraps nude primitives with a Tailwind style layer and ships precompiled, prefixed CSS. Sibling of lotus, web only.
+
+Every component is the `@journ/nude` primitive of the same name plus a style layer. Behavior, state and accessibility come from nude; bloom adds classes, icons and enter animations. The API matches nude's, plus variant props such as `tone` and `size`.
+
+## Install
+
+```sh
+pnpm add @journ/bloom react react-dom
+```
+
+## Usage
+
+Import the stylesheet once, at the root of the app. It is precompiled, so the app does not need Tailwind.
+
+```ts
+import '@journ/bloom/styles.css'
+```
+
+```tsx
+import { Button } from '@journ/bloom/button'
+import { Dialog } from '@journ/bloom/dialog'
+
+function Example() {
+	return (
+		<Dialog.Root>
+			<Dialog.Trigger asChild>
+				<Button tone='coral'>Delete</Button>
+			</Dialog.Trigger>
+			<Dialog.Content>
+				<Dialog.Title>Delete file</Dialog.Title>
+				<Dialog.Description>This cannot be undone.</Dialog.Description>
+				<Dialog.Actions>
+					<Dialog.Close asChild>
+						<Button tone='ghost'>Cancel</Button>
+					</Dialog.Close>
+				</Dialog.Actions>
+			</Dialog.Content>
+		</Dialog.Root>
+	)
+}
+```
+
+Every component has its own entry (`@journ/bloom/button`, `@journ/bloom/dialog`, ...). `@journ/bloom` exports all of them.
+
+### With your own Tailwind
+
+Apps that already run Tailwind v4 can skip `styles.css`, import the tokens and scan the package instead. The class names are plain, unprefixed utilities and the tokens are named `bloom-*`.
+
+```css
+@import 'tailwindcss';
+@import '@journ/bloom/tokens.css';
+@source '../node_modules/@journ/bloom/dist';
+```
+
+## Design system
+
+[DESIGN.md](./DESIGN.md) describes the look: color and tones, themes, shape, typography, layout, motion, the component list, and the rules that `pnpm lint` enforces. Read it before adding or changing a component.

package/dist/accordion-parts.d.ts

@@ -0,0 +1,9 @@
+import * as Nude from "@journ/nude/accordion-parts";
+import { ComponentPropsWithRef } from "react";
+//#region src/accordion-parts.d.ts
+declare const Root: any;
+declare const Item: ({ className, ...props }: ComponentPropsWithRef<typeof Nude.Item>) => import("react").JSX.Element;
+declare const Trigger: ({ className, children, ...props }: ComponentPropsWithRef<typeof Nude.Trigger>) => import("react").JSX.Element;
+declare const Content: ({ className, children, ...props }: ComponentPropsWithRef<typeof Nude.Content>) => import("react").JSX.Element;
+//#endregion
+export { Content, Item, Root, Trigger };

package/dist/accordion-parts.js

@@ -0,0 +1,37 @@
+"use client";
+import { cn } from "./lib/cn.js";
+import { pressReset } from "./lib/interactive.js";
+import { useExpand } from "./lib/use-enter.js";
+import { displayHeading } from "./lib/text-styles.js";
+import * as Nude from "@journ/nude/accordion-parts";
+import { ChevronDown } from "lucide-react";
+import { jsx, jsxs } from "react/jsx-runtime";
+//#region src/accordion-parts.tsx
+const Root = Nude.Root;
+const Item = ({ className, ...props }) => /* @__PURE__ */ jsx(Nude.Item, {
+	...props,
+	className: cn("border-b border-current/15 last:border-b-0", className)
+});
+const Trigger = ({ className, children, ...props }) => /* @__PURE__ */ jsxs(Nude.Trigger, {
+	...props,
+	classNames: { header: "flex" },
+	className: cn(pressReset, displayHeading, "group flex flex-1 cursor-default items-center justify-between gap-4 py-4 text-left outline-none", "focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-bloom-sky disabled:opacity-50", className),
+	children: [children, /* @__PURE__ */ jsx(ChevronDown, {
+		"aria-hidden": true,
+		className: "size-4 shrink-0 transition-transform group-data-[state=open]:rotate-180"
+	})]
+});
+const Content = ({ className, children, ...props }) => {
+	const element = useExpand();
+	return /* @__PURE__ */ jsx(Nude.Content, {
+		ref: element,
+		...props,
+		className: "overflow-hidden",
+		children: /* @__PURE__ */ jsx("div", {
+			className: cn("pb-4 text-sm/5", className),
+			children
+		})
+	});
+};
+//#endregion
+export { Content, Item, Root, Trigger };

package/dist/accordion.d.ts

@@ -0,0 +1,10 @@
+import { Content, Item, Trigger } from "./accordion-parts.js";
+//#region src/accordion.d.ts
+declare const Accordion: {
+  Root: any;
+  Item: typeof Item;
+  Trigger: typeof Trigger;
+  Content: typeof Content;
+};
+//#endregion
+export { Accordion };

package/dist/accordion.js

@@ -0,0 +1,10 @@
+import { Content, Item, Root, Trigger } from "./accordion-parts.js";
+//#region src/accordion.tsx
+const Accordion = {
+	Root,
+	Item,
+	Trigger,
+	Content
+};
+//#endregion
+export { Accordion };

package/dist/alert-dialog-parts.d.ts

@@ -0,0 +1,16 @@
+import { Actions } from "./lib/modal-parts.js";
+import { centeredPanel } from "./lib/overlay.js";
+import { VariantProps } from "./lib/tv.js";
+import { ComponentPropsWithRef } from "react";
+import * as Nude from "@journ/nude/alert-dialog-parts";
+//#region src/alert-dialog-parts.d.ts
+declare const Root: any;
+declare const Trigger: any;
+declare const Cancel: any;
+declare const Action: any;
+type ContentProps = Omit<ComponentPropsWithRef<typeof Nude.Content>, 'classNames' | 'overlayRef'> & VariantProps<typeof centeredPanel>;
+declare const Content: ({ tone, className, ...props }: ContentProps) => import("react").JSX.Element;
+declare const Title: ({ className, ...props }: ComponentPropsWithRef<typeof Nude.Title>) => import("react").JSX.Element;
+declare const Description: ({ className, ...props }: ComponentPropsWithRef<typeof Nude.Description>) => import("react").JSX.Element;
+//#endregion
+export { Action, Actions, Cancel, Content, Description, Root, Title, Trigger };

package/dist/alert-dialog-parts.js

@@ -0,0 +1,33 @@
+"use client";
+import { cn } from "./lib/cn.js";
+import { modalPanelEnter } from "./lib/use-enter.js";
+import { displayTitle, mutedText } from "./lib/text-styles.js";
+import { Actions } from "./lib/modal-parts.js";
+import { centeredPanel } from "./lib/overlay.js";
+import { ModalContent } from "./lib/modal-content.js";
+import { jsx } from "react/jsx-runtime";
+import * as Nude from "@journ/nude/alert-dialog-parts";
+//#region src/alert-dialog-parts.tsx
+const Root = Nude.Root;
+const Trigger = Nude.Trigger;
+const Cancel = Nude.Cancel;
+const Action = Nude.Action;
+const Content = ({ tone, className, ...props }) => /* @__PURE__ */ jsx(ModalContent, {
+	content: Nude.Content,
+	enter: modalPanelEnter,
+	...props,
+	className: centeredPanel({
+		tone,
+		class: className
+	})
+});
+const Title = ({ className, ...props }) => /* @__PURE__ */ jsx(Nude.Title, {
+	...props,
+	className: cn(displayTitle, className)
+});
+const Description = ({ className, ...props }) => /* @__PURE__ */ jsx(Nude.Description, {
+	...props,
+	className: cn(mutedText, className)
+});
+//#endregion
+export { Action, Actions, Cancel, Content, Description, Root, Title, Trigger };

package/dist/alert-dialog.d.ts

@@ -0,0 +1,15 @@
+import { Actions } from "./lib/modal-parts.js";
+import { Content, Description, Title } from "./alert-dialog-parts.js";
+//#region src/alert-dialog.d.ts
+declare const AlertDialog: {
+  Root: any;
+  Trigger: any;
+  Content: typeof Content;
+  Title: typeof Title;
+  Description: typeof Description;
+  Actions: typeof Actions;
+  Cancel: any;
+  Action: any;
+};
+//#endregion
+export { AlertDialog };

package/dist/alert-dialog.js

@@ -0,0 +1,15 @@
+import { Actions } from "./lib/modal-parts.js";
+import { Action, Cancel, Content, Description, Root, Title, Trigger } from "./alert-dialog-parts.js";
+//#region src/alert-dialog.tsx
+const AlertDialog = {
+	Root,
+	Trigger,
+	Content,
+	Title,
+	Description,
+	Actions,
+	Cancel,
+	Action
+};
+//#endregion
+export { AlertDialog };

package/dist/alert.d.ts

@@ -0,0 +1,48 @@
+import { VariantProps } from "./lib/tv.js";
+import { ComponentPropsWithRef } from "react";
+//#region src/alert.d.ts
+declare const alertRoot: import("tailwind-variants").TVReturnType<{
+  tone: {
+    readonly surface: "bg-bloom-surface dark:bg-bloom-surface-dark font-bloom-display text-bloom-foreground dark:text-bloom-foreground-dark border border-bloom-line dark:border-bloom-line-dark";
+    readonly coral: string;
+    readonly yellow: string;
+    readonly indigo: string;
+    readonly mint: string;
+    readonly sky: string;
+  };
+}, undefined, "rounded-bloom flex items-start gap-3 p-4", {
+  tone: {
+    readonly surface: "bg-bloom-surface dark:bg-bloom-surface-dark font-bloom-display text-bloom-foreground dark:text-bloom-foreground-dark border border-bloom-line dark:border-bloom-line-dark";
+    readonly coral: string;
+    readonly yellow: string;
+    readonly indigo: string;
+    readonly mint: string;
+    readonly sky: string;
+  };
+}, undefined, import("tailwind-variants").TVReturnTypeLike<{
+  tone: {
+    readonly surface: "bg-bloom-surface dark:bg-bloom-surface-dark font-bloom-display text-bloom-foreground dark:text-bloom-foreground-dark border border-bloom-line dark:border-bloom-line-dark";
+    readonly coral: string;
+    readonly yellow: string;
+    readonly indigo: string;
+    readonly mint: string;
+    readonly sky: string;
+  };
+}, undefined>>;
+type RootProps = ComponentPropsWithRef<'div'> & VariantProps<typeof alertRoot>;
+declare const Root: ({ tone, className, ...props }: RootProps) => import("react").JSX.Element;
+declare const Icon: ({ className, ...props }: ComponentPropsWithRef<'span'>) => import("react").JSX.Element;
+declare const Body: ({ className, ...props }: ComponentPropsWithRef<'div'>) => import("react").JSX.Element;
+declare const Title: ({ className, ...props }: ComponentPropsWithRef<'p'>) => import("react").JSX.Element;
+declare const Description: ({ className, ...props }: ComponentPropsWithRef<'p'>) => import("react").JSX.Element;
+declare const Actions: ({ className, ...props }: ComponentPropsWithRef<'div'>) => import("react").JSX.Element;
+declare const Alert: {
+  Root: typeof Root;
+  Icon: typeof Icon;
+  Body: typeof Body;
+  Title: typeof Title;
+  Description: typeof Description;
+  Actions: typeof Actions;
+};
+//#endregion
+export { Alert, type RootProps as AlertProps };