@carissa-io/theme-default 0.0.0-stage → 0.1.0

package/DESIGN.md

@@ -0,0 +1,174 @@
+# Carissa Default theme
+
+**Swiss precision for high-performance interfaces.** International Typographic Style: information over decoration.
+
+This is the design document of the **Carissa Default theme** (`@carissa-io/theme-default`): the decisions behind its
+values. The components are style-agnostic; this theme gives them their look through SCSS variable overrides in
+[scss/index.scss](scss/index.scss), and its palette and shared values (radius, focus ring, transition...) are Sass
+variables at the top of that file. Other themes (tech terminal, brutalist, ...) are their own `theme-<name>` repositories,
+never changes to the components.
+
+## Principles
+- **Objective clarity:** information is prioritized over decoration.
+- **Mathematical grid:** precise alignment and spacing, square corners.
+- **High contrast:** absolute black (`#000`) for primary actions and focus; neutral scales for meta-data.
+
+## Palette
+| Role | Value |
+| :--- | :--- |
+| Primary | `#000000` |
+| Surface | `#fafafa` / `#f5f5f5` |
+| Border (fields) | `#737373` (hover and focus: `#000`, focus adds a 1px ring) |
+| Text (body) | `#171717` |
+| Text (meta, placeholder) | `#737373` (4.7:1; lighter greys only for disabled states) |
+
+## Typography
+| Variant | Purpose | Style |
+| :--- | :--- | :--- |
+| `h1` | Primary page header | Black (900), tight tracking |
+| `h2` | Section header | Black (900) |
+| `h3` | Sub-section | Bold (700) |
+| `body` | Main content | Regular (400) |
+| `label` | Metadata / tags / field labels | Bold (700), uppercase, widest tracking |
+| `mono` | System data | Technical precision |
+
+Font family: a neutral grotesque stack, `Helvetica Neue, Helvetica, Arial, Liberation Sans, sans-serif`, in keeping with
+the International Typographic Style. No webfont is loaded, so a theme never depends on the network. Field text is
+1rem (16px, which also avoids the zoom-on-focus of mobile browsers); labels are 11px.
+
+## Buttons
+Three variants from [components-button](components/components-button), all square, 44px tall, with the same uppercase,
+bold, tracked 11px label as the field labels and 200ms color transitions.
+- **Primary:** black background, white text; hover `#262626`, active `#404040`.
+- **Secondary:** white background, 1px `#737373` border; the border turns black on hover.
+- **Ghost:** transparent; a `#f5f5f5` surface appears on hover.
+- **Disabled:** `#a3a3a3` text on a `#f5f5f5` surface (primary), or a lighter border (secondary, ghost); no hover.
+- **Focus:** keyboard focus (`:focus-visible`) follows the general rule below: secondary and ghost thicken their border to
+  2px; primary (filled) draws a 1px black ring offset by 2px.
+
+## Checkbox
+From [components-checkbox](components/components-checkbox): the whole row (box and label) is the click target and is at
+least 44px tall. The label is body text (1rem, `#171717`), not the uppercase field-label style.
+- **Box:** 20px square, square corners, 1px `#737373` border; the border turns black on hover.
+- **Checked:** black background with a white Lucide `check` mark.
+- **Disabled:** `#a3a3a3` label and mark on a `#f5f5f5` box with a `#d4d4d4` border; no hover.
+- **Error:** `#dc3545`, 13px, under the row; the box border turns red too. The built-in error shows after the first
+  interaction, an error passed by the parent shows at once.
+- **Focus:** keyboard focus (`:focus-visible`): an empty box thickens its border to 2px; a checked (black) box draws a 1px
+  black ring offset by 2px.
+
+## Switch
+From [components-switch](components/components-switch), a checkbox with `role="switch"`, same row, label and error.
+- **Track:** 40 x 20px, square, white with a 1px `#737373` border (black on hover); a `#737373` square thumb.
+- **On:** black track, white thumb; the thumb slides in 200ms, like the other color transitions.
+- **Disabled:** `#f5f5f5` track with a `#d4d4d4` border and an `#a3a3a3` thumb.
+- **Focus:** an off track thickens its border to 2px; an on (black) track draws a 1px black ring offset by 2px.
+
+## Radio group
+From [components-radio-group](components/components-radio-group): a fieldset whose legend uses the field-label style
+(11px, bold, uppercase, tracked, `#737373`). Each option row (dot and label) is the click target and is at least 44px
+tall; the label is body text (1rem, `#171717`).
+- **Dot:** 20px circle (the one round shape in the theme: a radio is a circle, so its radius is not the square `$radius`),
+  1px `#737373` border; the border turns black on hover.
+- **Checked:** black border with a 10px black inner dot on white.
+- **Disabled:** `#a3a3a3` label on a `#f5f5f5` dot with a `#d4d4d4` border; no hover. A single option can be disabled too.
+- **Error:** `#dc3545`, 13px, under the options; the dots get a red border. The built-in error shows after the first
+  interaction (a change, or focus leaving the group), an error passed by the parent shows at once.
+- **Focus:** keyboard focus (`:focus-visible`) thickens the dot's border from 1px to 2px, black, with no separate ring (so a
+  checked radio never reads as a double circle); the arrow keys move the selection.
+
+## Textarea
+From [components-textarea](components/components-textarea), which is the input with `multiline`: it uses exactly the
+input's look (notched uppercase label, 1px `#737373` border that turns black on hover and focus, 1px black focus ring,
+`#dc3545` error). Only the control differs:
+- **Height:** at least 6rem (about three lines of 16px text) and resizable vertically only, so it never breaks the grid;
+  `rows` sets the initial height.
+- **Disabled and error:** same as the input (`#a3a3a3` on `#f5f5f5`; red border and 13px message).
+
+## Slider
+From [components-slider](components/components-slider), a native range input; the row is at least 44px tall. The label
+uses the field-label style (11px, bold, uppercase, tracked, `#737373`); the optional live value, on the same line at
+the right, is body text (1rem, `#171717`).
+- **Track:** a 2px `#737373` line, square; the part before the thumb is black.
+- **Thumb:** 20px black square with a 1px white border (so it stays distinct where it crosses the track); `#262626` on
+  hover, `#404040` while dragging.
+- **Disabled:** `#a3a3a3` label, thumb and fill on a `#d4d4d4` track; no hover.
+- **Focus:** keyboard focus (`:focus-visible`) draws a 1px black ring offset by 2px around the thumb.
+
+## Popover
+From [components-popover](components/components-popover), the floating panel behind the select, combobox and date picker:
+white, a 1px `#737373` border, square corners and no shadow (flat, like the rest of the theme), 4px below its anchor.
+It fades in over 200ms and opens above the anchor when there is no room below. It has no padding of its own: the
+content (a list, a calendar) brings its spacing.
+
+## Listbox
+From [components-listbox](components/components-listbox), the option list used inside the popover. Each option is at
+least 44px tall, body text (1rem, `#171717`) with 0.75rem of horizontal padding.
+- **Active** (hover or keyboard cursor): `#f5f5f5` surface.
+- **Selected:** bold text with a 2px black bar on the inline-start edge.
+- **Disabled:** `#a3a3a3`, no hover.
+- **Empty:** a `#737373` message with 0.75rem of padding.
+- **Height:** at most 15rem; longer lists scroll.
+
+## Select
+From [components-select](components/components-select): a custom list, so it looks the same in every browser. The closed
+field is the Input (notched uppercase label, 1px `#737373` border, black on hover and focus, 44px tall); the value reads
+as body text, and the placeholder is `#737373` like the input placeholder. A 16px `#737373` chevron sits on the right
+and turns black; when the list is open it rotates 180 degrees over 200ms and the border stays black. The open panel is
+the Popover and the options are the Listbox, as wide as the field. Errors, required marker and disabled look are the
+Input's.
+
+## Combobox
+From [components-combobox](components/components-combobox): the Select field with a text input in place of the button, so
+the user can type to filter the list. Same Input look (notched uppercase label, 1px `#737373` border, black on hover and
+focus, 44px tall), same 16px `#737373` chevron that turns black and rotates 180 degrees when the list is open. The text
+is body text (`#171717`) and the placeholder `#737373`. A press anywhere in the box focuses the input (the chevron is
+decorative, not a button); the list opens when typing or with the arrow keys. The panel is the Popover and the options
+the Listbox, as wide as the field; a message such as "No results" uses the Listbox empty style. Errors, required marker
+and disabled look are the Input's.
+
+## Upload
+From [components-upload](components/components-upload): the Input field turned into a dropzone. The box keeps the
+notched uppercase label and the 1px `#737373` border but dashed, black on hover; while files are dragged over it the
+border is black and the background `#f5f5f5`. The zone is at least 5.5rem tall and centers its content as muted (`#737373`)
+body text, and the whole box is the click target. Chosen files are listed below the zone as 44px rows split by a 1px
+`#e5e5e5` line: the name in body text with an ellipsis, and a 44px square remove button (a multiplication sign, `#737373`,
+black on hover, 1px black focus ring). The focus ring of the box is the Input's. Errors, required marker and disabled look
+(`#a3a3a3` on `#f5f5f5`) are the Input's.
+
+## Calendar
+From [components-calendar](components/components-calendar): a standalone month grid (the date picker shows it inside the
+Popover, which draws the only border). It has no outer border. The header is two 44px navigation buttons (muted
+chevrons that turn black, 1px black focus ring drawn inside) around the month and year in the label style (11px, bold,
+uppercase, `0.1em` tracking, `#737373`); the weekday row uses the same style. Days are 44px squares in body text
+(`#171717`) with square corners and a `#f5f5f5` hover. The selected day is a black square with white text; today is a
+1px black border, drawn inside the square so nothing shifts. Days outside `min..max` are `#a3a3a3` with no hover, and
+the days of the neighbor months are left empty. The keyboard focus ring is 1px black, inset. The grid always shows six
+weeks so the height never changes between months.
+
+## Date picker
+From [components-date-picker](components/components-date-picker): the Select field with a calendar in the panel. The closed
+field is the Input (notched uppercase label, 1px `#737373` border, black on hover and focus, 44px tall); the chosen date
+reads as body text (for example "Oct 14, 2026") and the placeholder is `#737373`. A 16px `#737373` calendar icon sits on the
+right and turns black on hover and while open; it does not rotate, and the border stays black while open. The open panel
+is the Popover (1px `#737373` border, no shadow) with 0.5rem of padding around the Calendar, as wide as the calendar
+needs, not as the field. Errors, required marker and disabled look are the Input's.
+
+## Search
+From [components-search](components/components-search): the Input of type search with two inline parts built on the input's
+`start` and `end` slots. The field is the Input's (notched uppercase label, 1px `#737373` border, black on hover and focus,
+44px tall; the keyboard focus rule below applies). A 20px `#737373` magnifier icon sits on the left and turns black while the
+field has the focus. The clear button appears on the right only while there is text: a 16px `#737373` cross in the Input's
+44px side-button box that turns black on hover; the browser's own clear button is hidden so the look is the same everywhere.
+Errors, required marker and disabled look are the Input's. The Input and Textarea accept `start` and `end` content (a prefix
+icon, a unit) in the same muted color (`#737373`) with `0.5rem` between the content and the text.
+
+## Keyboard focus (all controls)
+One rule keeps the controls coherent: **an outlined control thickens its own border from 1px to 2px, black** (text fields,
+select, combobox, date picker, textarea, upload, empty checkbox, off switch, radio, secondary and ghost buttons); **a filled
+(black) control draws a separate 1px black ring offset by 2px**, because a thicker border would be invisible on a black fill
+(primary button, checked checkbox, on switch, slider thumb). Calendar days and the upload remove button use an inset 1px ring.
+
+## Guidelines
+- **Accessibility:** 4.5:1 contrast for body text; interactive elements are at least 44px tall.
+- **Motion:** subtle, 200-300ms. Hover gives immediate feedback (border or color shift).

package/README.md

@@ -1,3 +1,46 @@
-# Temporary Holding Version
+# @carissa-io/theme-default
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The Carissa Default theme: **Swiss minimalism** (square corners, absolute black for primary actions and focus, a neutral
+grey scale, a neutral grotesque type stack). The Carissa components ship neutral defaults and no look of their own; this
+package gives them one by overriding their SCSS variables. The decisions behind the values are in [DESIGN.md](DESIGN.md).
+
+## Install
+```bash
+npm install @carissa-io/theme-default
+```
+The compiled CSS needs nothing else. To compile the SCSS yourself, also install the components you use (they are optional
+peer dependencies).
+
+## Use it
+1. **Compiled CSS** (nothing to compile; the components must still be installed to render):
+   ```js
+   import '@carissa-io/theme-default/css'
+   ```
+   It is also the package's main export, so `import '@carissa-io/theme-default'` works with a bundler that handles CSS.
+2. **SCSS source:** forward or `@use` it from your own Sass entry, with `@carissa-io/*` resolvable (`node_modules` on the
+   load path):
+   ```scss
+   @use '@carissa-io/theme-default/scss';
+   ```
+3. **A starting point for a new theme:** copy `scss/index.scss` and change the values. In the Carissa workspace,
+   `scripts/new-theme.sh <name> "<description>"` does this and sets up the repo.
+
+## What it configures
+`components-input`, `-button`, `-checkbox`, `-switch`, `-radio-group`, `-slider`, `-popover`, `-listbox`, `-select`,
+`-combobox`, `-upload`, `-calendar`, `-date-picker` and `-search`. `components-email`, `-password`, `-url` and `-textarea`
+are styled through the input.
+
+## Change a value
+The palette and the values shared by every component (radius, minimum height, focus ring, transition, label style, dropdown
+arrow) are Sass variables at the top of `scss/index.scss`; each component has one `@use ... with (...)` block of overrides
+below. Change the value, run `npm run build`, and update [DESIGN.md](DESIGN.md) if the decision changes.
+
+## Develop
+```bash
+npm install
+npm run lint    # compile, fail on any Sass error or warning
+npm test        # builds, then checks every component root has rules and dist/ is current
+npm run build   # dist/index.css
+```
+`dist/` is not committed; it is built before every publish. The package ships `dist`, `scss` and `DESIGN.md`. Releases
+follow the Carissa project rules: branch and pull request, CI publishes when the version on `main` is new.