@misoto22/design 0.3.1 → 0.6.0

package/dist/agent/index.md

@@ -0,0 +1,131 @@
+# @misoto22/design 0.6.0
+
+> Monochrome design system: portable CSS tokens and accessible React 19
+> primitives. Components ship compiled — import them, do not copy them.
+
+Install: `npm install @misoto22/design`. Styles: `import '@misoto22/design/styles.css'`.
+
+One component, in full, offline:
+
+```bash
+npx misoto22-design docs <Component>
+```
+
+## Theme axes
+
+Attributes, independent, and they work on any element — not just the root.
+An unset axis is the default.
+
+- `data-chart-palette`: `chroma` (unset = the neutral series ramp)
+- `data-density`: `compact` (unset = comfortable)
+- `data-mode`: `dark` `light` (unset = follows the app)
+- `data-motion`: `snappy` `still` (unset = calm)
+- `data-radius`: `round` `sharp` (unset = the default radius ladder)
+- `data-rules`: `firm` `quiet` (unset = hairline)
+- `data-surface`: `cool` `glass` `warm` (unset = paper)
+- `data-table-density`: `compact` (unset = comfortable — whatever `data-density` is doing around it)
+- `data-type`: `bookish` `grotesk` (unset = editorial)
+
+There is no `data-accent` attribute: `--accent` is a CSS custom property,
+re-pointed in a stylesheet.
+
+## Components
+
+### Actions
+
+- **Button** — The system’s action, on the same corner as the field beside it.
+- **FloatingIconButton** — A round action pinned to a screen corner.
+
+### Forms
+
+- **Field** — A labelled form row: label, control, and the one message below it.
+- **Input** — A single line of text entry.
+- **Textarea** — Multi-line text entry, resizable vertically only.
+- **Select** — A choice from a list, styled the whole way down.
+- **NativeSelect** — The platform’s own picker, restyled where it can be.
+- **Checkbox** — A choice that takes effect when the form is submitted.
+- **RadioGroup** — A set of mutually exclusive choices.
+- **Switch** — A setting that takes effect immediately.
+- **Combobox** — A select you can type into.
+- **DatePicker** — A date — or a span of them — chosen from a calendar.
+- **Slider** — A value chosen along a range.
+- **ToggleGroup** — A segmented control: several options, one strip.
+
+### Navigation
+
+- **Tabs** — One strip, several panels.
+- **Accordion** — Disclosure rows that open in place.
+- **Breadcrumb** — Where you are, as a path.
+- **Pagination** — Numbered pages, with the middle elided.
+- **NavItem** — A row in a sidebar.
+- **Collapsible** — One thing that opens, on its own.
+
+### Overlays
+
+- **Dialog** — A modal surface: portal, scrim, centred panel.
+- **DropdownMenu** — A menu of actions.
+- **Tooltip** — A short label on hover and on focus.
+- **Popover** — A panel anchored to a control, holding content you can interact with.
+- **Sheet** — A panel docked to an edge of the viewport.
+- **ContextMenu** — The menu a right-click opens.
+- **SearchableMenu** — A menu of actions you can type into.
+- **Command** — A filterable list of actions — the ⌘K surface.
+
+### Feedback
+
+- **Spinner** — The one “working” indicator — a ring, never a shimmer.
+- **Skeleton** — The shape of the page, before the page.
+- **Progress** — A bar that fills, or sweeps when the end is unknown.
+- **Alert** — A message about the page, in place.
+- **EmptyState** — A collection with nothing in it — yet.
+- **ErrorState** — A page that could not be shown.
+- **Toast** — A transient confirmation, mounted once near the app root.
+
+### Display
+
+- **Badge** — A count or a state, set in mono so it reads as metadata.
+- **Tag** — A subject label — a topic, a technology, a filter facet.
+- **Kbd** — A key on a keyboard, set as one.
+- **Avatar** — A person, as a circle, with initials until the image lands.
+- **StatusDot** — The dot beside a status word.
+- **Steps** — A numbered sequence, as a rail — one thing after another, with a rule through them.
+- **StatusPill** — A live state, named: a dot plus an uppercase mono label.
+- **LinkArrow** — The mark on a link that leaves the page.
+- **Separator** — A rule, in the three weights a monochrome page needs.
+- **Diagram** — A flow or architecture figure, drawn out of the system’s own parts.
+- **FigureBand** — A row of counted facts, divided by hairlines and nothing else.
+
+### Surfaces
+
+- **Article** — The long-form reading surface — everything a Markdown pipeline emits, in this system’s type.
+- **Card** — A bounded surface, with no shadow under it.
+- **AppShell** — Two columns on a desktop, a drawer on a phone.
+- **Calendar** — A month, as a grid of days.
+- **ScrollArea** — A box that scrolls, with a scrollbar that looks the same everywhere.
+
+### Data
+
+- **Table** — A ruled data table — alignment, sorting and rules all per column.
+- **Heatmap** — A grid of values read by weight.
+- **Sparkline** — A run of numbers at the size of a word.
+- **BarList** — A ranked list, with the bar behind the name rather than beside it.
+- **BigNumber** — One number, at the size of a headline.
+- **BulletChart** — A measure, its target, and the bands that say whether it is any good.
+
+### Charts
+
+- **AreaChart** — A filled series over a continuous axis, where the area means something.
+- **BarChart** — Discrete categories compared by length.
+- **LineChart** — Several series compared over a continuous axis.
+- **ComposedChart** — Bars and lines over one axis — the volume, and the rate it moved at.
+- **PieChart** — Parts of one whole.
+- **RadarChart** — A profile across several named dimensions.
+- **RadialChart** — Values on an arc — a gauge, or a few totals against one scale.
+- **SankeyChart** — Where a quantity goes as it moves through stages.
+- **ScatterChart** — Two measures against each other, one mark per observation.
+- **FunnelChart** — Stages that only ever narrow.
+- **TreemapChart** — Part of a whole, when the whole has too many parts for a pie — and the parts nest.
+- **BoxPlot** — The spread of a measurement, per category.
+- **Histogram** — The shape of one distribution.
+- **WaterfallChart** — How a total got from one figure to another.
+- **Facet** — The same chart once per group, on one shared scale.

package/dist/article.css

@@ -0,0 +1,393 @@
+/* ==========================================================================
+   ARTICLE — the long-form reading surface
+   --------------------------------------------------------------------------
+   The one place in this package that styles TAGS rather than components, and
+   the reason is that its input is not JSX: it is whatever a Markdown or MDX
+   pipeline produced. There is no component to hang a class on, so the contract
+   has to be the element names themselves.
+
+   Scoped to `[data-m22-article]`, which the `Article` component writes. Nothing
+   here leaks: a page that does not opt in is untouched, and a component
+   rendered INSIDE an article keeps its own classes, because every rule below
+   is a bare element selector at specificity 0,1,1 — a utility on a component
+   wins.
+
+   It reads only tokens. Re-point the palette or move the radius factor and the
+   article moves with everything else, which is the whole reason this is here
+   rather than in each consuming site: three sites hand-rolling a prose
+   stylesheet is three prose stylesheets that drift.
+   ========================================================================== */
+
+[data-m22-article] {
+  /* A measure, not a width. A narrower column still wins, and a figure or a
+     table opts out of it explicitly below. */
+  max-width: var(--w-reading);
+  color: var(--ink-2);
+  font-family: var(--sans);
+  font-size: 1rem;
+  font-weight: 300;
+  line-height: 1.75;
+}
+
+/* ─── Headings ─────────────────────────────────────────────────────────────
+   The type ladder, unchanged. An article does not get its own scale — it is
+   the same five steps every other surface climbs, which is what makes a post
+   and a component page read as one publication. */
+
+[data-m22-article] :is(h1, h2, h3, h4, h5, h6) {
+  margin: 0;
+  color: var(--ink);
+  font-family: var(--font-heading, var(--serif));
+  font-weight: 400;
+  line-height: 1.25;
+  /* An anchored heading has to clear the masthead it scrolls under. */
+  scroll-margin-top: var(--scroll-offset);
+}
+[data-m22-article] h1 {
+  font-size: var(--fs-title);
+  letter-spacing: -0.02em;
+}
+[data-m22-article] h2 {
+  font-size: var(--fs-heading);
+}
+[data-m22-article] h3 {
+  font-size: var(--fs-sub);
+}
+[data-m22-article] h4 {
+  font-size: var(--fs-item);
+}
+[data-m22-article] :is(h5, h6) {
+  font-family: var(--mono);
+  font-size: 11px;
+  font-weight: 400;
+  letter-spacing: 0.2em;
+  text-transform: uppercase;
+  color: var(--ink-3-aa);
+}
+
+/* ─── Rhythm ───────────────────────────────────────────────────────────────
+   Every block gets air ABOVE it and none below, the first one gets none at
+   all, and a heading gets more air above than below so it belongs to what
+   follows rather than to what it interrupts.
+
+   The reset uses `:where()`, and that is the load-bearing part. A plain
+   `[data-m22-article] p { margin: 0 }` is specificity 0,1,1 and outranks
+   `[data-m22-article] > * + *` at 0,1,0 — so the reset silently won and every
+   paragraph in the article lost its spacing, which is exactly the defect this
+   replaces. `:where()` contributes nothing, so the reset and the rhythm sit at
+   the same weight and source order decides, which is what a reset is for. */
+
+[data-m22-article] :where(*) {
+  margin: 0;
+}
+[data-m22-article] > * + * {
+  margin-block-start: 1.25em;
+}
+/* `:is()` takes the specificity of its heaviest argument, so these two land at
+   0,1,1 and win over the general rule above whatever their order. */
+[data-m22-article] > :is(h1, h2, h3, h4, h5, h6) {
+  margin-block-start: 2.25em;
+}
+[data-m22-article] > :is(h1, h2, h3, h4, h5, h6) + * {
+  margin-block-start: 0.75em;
+}
+[data-m22-article] > :first-child {
+  margin-block-start: 0;
+}
+
+/* The opening paragraph carries the piece. Marked, not guessed: an author
+   writes `<p class="lead">` (or a pipeline emits it), rather than the
+   stylesheet deciding that whatever came first is a standfirst. */
+[data-m22-article] p.lead {
+  font-size: var(--fs-item);
+  line-height: 1.6;
+  color: var(--ink);
+}
+
+/* ─── Inline ─────────────────────────────────────────────────────────────── */
+
+[data-m22-article] a {
+  color: var(--ink);
+  text-decoration: underline;
+  text-decoration-color: var(--rule-2);
+  text-underline-offset: 4px;
+  transition: text-decoration-color var(--fast) var(--ease);
+}
+[data-m22-article] a:hover {
+  text-decoration-color: var(--ink);
+}
+[data-m22-article] strong {
+  color: var(--ink);
+  font-weight: 500;
+}
+[data-m22-article] em {
+  font-style: italic;
+}
+[data-m22-article] mark {
+  background: var(--accent-muted);
+  color: var(--ink);
+  padding-inline: 0.2em;
+}
+[data-m22-article] abbr[title] {
+  text-decoration: underline dotted var(--rule-2);
+  text-underline-offset: 3px;
+}
+[data-m22-article] :is(sub, sup) {
+  font-size: 0.75em;
+  line-height: 0;
+}
+
+/* ─── Lists ────────────────────────────────────────────────────────────────
+   The marker is a token, not a glyph the browser picks: a default disc is a
+   filled circle at whatever size the font decides, and this system's only
+   filled circle is a status dot. */
+
+[data-m22-article] :is(ul, ol) {
+  padding-inline-start: 1.4em;
+}
+[data-m22-article] :is(ul, ol) :is(ul, ol) {
+  margin-block-start: 0.4em;
+}
+[data-m22-article] li + li {
+  margin-block-start: 0.4em;
+}
+/* A paragraph or a fence nested inside a list item is still a block. */
+[data-m22-article] li > * + * {
+  margin-block-start: 0.6em;
+}
+[data-m22-article] li::marker {
+  color: var(--ink-3-aa);
+  font-size: 0.9em;
+}
+[data-m22-article] ul {
+  list-style: none;
+  padding-inline-start: 1.15em;
+}
+[data-m22-article] ul > li {
+  position: relative;
+}
+/* A hairline dash, which is the marker the rest of the system uses. */
+[data-m22-article] ul > li::before {
+  content: '';
+  position: absolute;
+  inset-inline-start: -1.15em;
+  inset-block-start: 0.85em;
+  width: 0.55em;
+  height: 1px;
+  background: var(--rule-2);
+}
+/* A task list already has its own marker — the checkbox. Both spellings,
+   because a pipeline may wrap the input in a label and `:has()` is what makes
+   the rule work either way. */
+[data-m22-article] ul > li:has(input[type='checkbox'])::before {
+  content: none;
+}
+[data-m22-article] li:has(input[type='checkbox']) {
+  padding-inline-start: 0;
+}
+[data-m22-article] input[type='checkbox'] {
+  accent-color: var(--accent);
+  margin-inline-end: 0.5em;
+  /* A published checklist REPORTS state; it does not collect it. Disabled at
+     full opacity, because the dimming a browser applies to a disabled control
+     is a hint that it is unavailable, not that it is unticked. */
+  opacity: 1;
+}
+[data-m22-article] li:has(input[type='checkbox']) label {
+  display: inline;
+  cursor: default;
+}
+
+[data-m22-article] dt {
+  color: var(--ink);
+  font-weight: 500;
+}
+[data-m22-article] dd {
+  margin-block-end: 0.75em;
+  padding-inline-start: 1em;
+  border-inline-start: 1px solid var(--rule);
+}
+
+/* ─── Quotation ────────────────────────────────────────────────────────────
+   A rule and a change of face, not italics and not a giant quote mark. */
+
+[data-m22-article] blockquote {
+  padding-inline-start: 1.25em;
+  border-inline-start: 2px solid var(--rule-hard);
+  color: var(--ink);
+  font-family: var(--serif);
+  font-size: var(--fs-item);
+  line-height: 1.55;
+}
+[data-m22-article] blockquote p + p {
+  margin-block-start: 0.6em;
+}
+[data-m22-article] blockquote cite {
+  display: block;
+  margin-block-start: 0.75em;
+  color: var(--ink-3-aa);
+  font-family: var(--mono);
+  font-size: 11px;
+  font-style: normal;
+  letter-spacing: 0.08em;
+}
+
+/* ─── Code ─────────────────────────────────────────────────────────────────
+   An inline span is a chip; a block is a plate. Neither is a second surface
+   colour — both sit on the one elevated step the system has. */
+
+[data-m22-article] code {
+  background: var(--stone);
+  border-radius: var(--radius-sm);
+  padding: 0.15em 0.4em;
+  color: var(--ink);
+  font-family: var(--mono);
+  font-size: 0.85em;
+}
+[data-m22-article] pre {
+  padding: 1rem 1.125rem;
+  overflow-x: auto;
+  background: var(--paper-2);
+  border: 1px solid var(--rule);
+  border-radius: var(--radius-lg);
+  font-size: 13px;
+  line-height: 1.7;
+  scrollbar-width: thin;
+  scrollbar-color: var(--rule-2) transparent;
+}
+[data-m22-article] pre code {
+  background: none;
+  border-radius: 0;
+  padding: 0;
+  font-size: inherit;
+}
+
+/* ─── Figures, media and tables ────────────────────────────────────────────
+   These are the three things allowed out of the measure: a table with six
+   columns and an image with a subject in it are both unreadable at 46rem. */
+
+[data-m22-article] :is(figure, table, .m22-wide) {
+  width: 100%;
+  max-width: none;
+}
+[data-m22-article] > figure {
+  margin-block-start: 2em;
+}
+[data-m22-article] :is(img, video) {
+  display: block;
+  max-width: 100%;
+  height: auto;
+  border-radius: var(--radius);
+}
+[data-m22-article] figcaption {
+  margin-block-start: 0.75em;
+  color: var(--ink-3-aa);
+  font-family: var(--mono);
+  font-size: 11px;
+  letter-spacing: 0.08em;
+  line-height: 1.6;
+}
+
+[data-m22-article] .m22-table-scroll {
+  overflow-x: auto;
+  scrollbar-width: thin;
+  scrollbar-color: var(--rule-2) transparent;
+}
+[data-m22-article] table {
+  border-collapse: collapse;
+  font-size: 0.9375rem;
+  text-align: start;
+}
+[data-m22-article] th {
+  padding: 0.65em 1.25em 0.65em 0;
+  border-block-end: 1px solid var(--rule-hard);
+  color: var(--ink-3-aa);
+  font-family: var(--mono);
+  font-size: 11px;
+  font-weight: 400;
+  letter-spacing: 0.2em;
+  text-transform: uppercase;
+  text-align: start;
+  white-space: nowrap;
+}
+[data-m22-article] td {
+  padding: 0.65em 1.25em 0.65em 0;
+  border-block-end: 1px solid var(--rule);
+  color: var(--ink-2);
+  vertical-align: baseline;
+}
+[data-m22-article] :is(th, td):last-child {
+  padding-inline-end: 0;
+}
+
+[data-m22-article] > hr {
+  margin-block-start: 2.5em;
+}
+[data-m22-article] hr {
+  border: 0;
+  border-block-start: 1px solid var(--rule);
+}
+
+[data-m22-article] kbd {
+  border: 1px solid var(--rule-2);
+  border-radius: var(--radius-sm);
+  padding: 0.1em 0.4em;
+  color: var(--ink-2);
+  font-family: var(--mono);
+  font-size: 0.8em;
+}
+
+/* ─── Mathematics ──────────────────────────────────────────────────────────
+   MathML, which is why there is no font to load and no second stylesheet: the
+   browser sets it in the surrounding face. A display formula is centred and
+   allowed to scroll, because a long equation is the one block that genuinely
+   cannot wrap. */
+
+[data-m22-article] math {
+  color: var(--ink);
+  font-size: 1.05em;
+}
+[data-m22-article] .m22-math {
+  /* `overflow-x: auto` alone turns the OTHER axis into `auto` too, which drew
+     a vertical scrollbar down the side of every formula. */
+  overflow-x: auto;
+  overflow-y: hidden;
+  padding-block: 0.35em;
+  scrollbar-width: thin;
+  scrollbar-color: var(--rule-2) transparent;
+}
+/* A block-level `math` is not affected by the container's `text-align`, so it
+   is centred the way any block is: by its own margins. */
+[data-m22-article] math[display='block'] {
+  display: block;
+  width: fit-content;
+  margin-inline: auto;
+}
+
+/* ─── Footnotes ────────────────────────────────────────────────────────────
+   Ruled off and set small: they are apparatus, not the piece. */
+
+[data-m22-article] > .footnotes {
+  margin-block-start: 3em;
+}
+[data-m22-article] .footnotes {
+  padding-block-start: 1.5em;
+  border-block-start: 1px solid var(--rule);
+  font-size: 0.875rem;
+}
+[data-m22-article] .footnotes h2 {
+  font-family: var(--mono);
+  font-size: 11px;
+  letter-spacing: 0.2em;
+  text-transform: uppercase;
+  color: var(--ink-3-aa);
+}
+/* The reference and its back-arrow keep the underline every other link in the
+   article has. Stripping it was a WCAG 1.4.1 failure and axe says so: a link
+   inside a block of text has to be distinguishable from the text without
+   relying on colour, and ink on --ink-2 is 2.14:1 — well under the 3:1 that
+   would let colour carry it alone. */
+[data-m22-article] .footnote-backref {
+  /* The glyph is the affordance; a name is not. */
+  font-size: 0.9em;
+}