@misoto22/folio 0.0.0 → 0.17.0

package/dist/agent/index.md

@@ -0,0 +1,185 @@
+# @misoto22/folio 0.17.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/folio`. Styles: `import '@misoto22/folio/styles.css'`. Website compositions add `website.css`, and `website-base.css` when the whole page is a website.
+
+One component, in full, offline:
+
+```bash
+npx @misoto22/folio docs <Component>
+```
+
+## Theme axes
+
+Attributes, independent, and they work on any element — not just the root.
+An unset axis is the default.
+
+- `data-accent`: `clay` `cobalt` `ember` `forest` `ink` `moss` `plum` (unset = ink)
+- `data-action`: `accent` `ink` (unset = accent)
+- `data-chart-palette`: `accent` `chroma` (unset = the neutral series ramp)
+- `data-density`: `comfortable` `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` `hairline` `quiet` (unset = hairline)
+- `data-surface`: `cool` `glass` `linen` `paper` `warm` (unset = paper)
+- `data-table-density`: `compact` (unset = comfortable — whatever `data-density` is doing around it)
+- `data-type`: `bookish` `editorial` `grotesk` (unset = editorial)
+- `data-voice`: `display` `quiet` (unset = display)
+
+`data-accent` re-points one token, `--clay`, which every component reads
+through `--accent`. A brand the package has never seen re-points it in a
+stylesheet instead; the attribute is the shipped set, not the only way in.
+
+## 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 — and, in row layout, the settings row.
+- **Input** — A single line of text entry.
+- **NumberField** — A number, typed or swept to.
+- **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.
+- **ColorPicker** — A colour, chosen or typed.
+- **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.
+- **Sidebar** — A navigation rail down the side of an application.
+- **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 — that filters with onClick and is dismissed with onRemove.
+- **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 — with words in it when the break has something to say.
+- **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.
+- **Text** — The system’s paragraph, on the second rung of the ink ladder.
+- **Heading** — A heading whose element and whose size are two decisions.
+- **Code** — A function name or a flag, inside a sentence.
+- **CodeBlock** — A multi-line snippet, on a plate, with a way to take it away.
+- **Markdown** — A Markdown string, rendered as this system’s components.
+- **Timestamp** — A date or a time, rendered the one way the system renders them.
+
+### 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.
+- **PageHeader** — A page opening: what this page is, and what qualifies it.
+- **Calendar** — A month, as a grid of days.
+- **ScrollArea** — A box that scrolls, with a scrollbar that looks the same everywhere.
+- **DescriptionList** — One record’s fields, as a real <dl> rather than a grid of divs.
+- **Toolbar** — The bar of actions at the edge of a working surface.
+- **AspectRatio** — A box that keeps its shape whatever is inside it.
+
+### Data
+
+- **Table** — A ruled data table — alignment, sorting and rules all per column.
+- **Heatmap** — A grid of values read by weight.
+- **CalendarHeatmap** — A year of daily readings, as a week-by-week grid.
+- **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.
+- **Metric** — One reading, on a plate: a label, a figure, and what qualifies 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.
+
+### Diagrams
+
+- **ArchitectureFigure** — A component map: services, datastores, trust boundaries, and what talks to what.
+- **WorkflowFigure** — A process in lanes and phases, with the main path drawn heavier than its branches.
+- **SequenceFigure** — A call chain over time: who asks whom, in what order, and what comes back.
+- **DataflowFigure** — A pipeline: where data comes from, what happens to it, and who ends up with it.
+- **LifecycleFigure** — A state machine: what something can be, and what moves it between states.
+- **DiagramCanvas** — A frame that a picture larger than it can be panned and zoomed inside.
+- **DiagramToolbar** — A bar of actions belonging to the surface underneath them.
+- **DiagramExportMenu** — Taking the figure off the page: PNG, JPEG, WebP, SVG and a 1200×630 share card.
+- **DiagramInspector** — What the reader just picked, written out beside the picture.
+- **DiagramMinimap** — Where you are in something bigger than the window.
+- **DiagramLegend** — The key: which drawn form means which kind of thing.
+
+## Website patterns
+
+- **SiteShell** — Page landmarks, footer groups and shared section headings.
+- **SiteNavigation** — Responsive navigation and explicit language or appearance choices.
+- **Portfolio** — An editorial introduction, featured images, records and a question card.
+- **PortfolioIndex** — Tabbed collections with a supporting editorial column.
+- **Collection** — Collection headings, search controls, featured records and empty states.
+- **Reading** — Article and project layouts, outlines, media and installation instructions.
+- **Contact** — A correspondence form, contact facts, questions and location imagery.
+- **Music** — Featured recordings, track rows and playlist collections.
+- **Timeline** — Career records, profile narratives and chronological lists.
+- **Recovery** — Loading, unavailable and missing-page states with recovery actions.
+- **Media** — Photograph collections, lightboxes, image details and map controls.
+- **Metrics** — Metric panels, accessible data tables and chart arrangements.
+- **SearchPalette** — Search results, actions and a detail view in one accessible modal.
+- **Content** — Formatted code, clipboard actions, step sequences and rich-content elements.
+- **Actions** — Share action menus and a scroll-to-top control.
+- **Conversation** — Conversation threads, answers, citations, composers and floating chat surfaces.
+- **Evidence** — Expandable traces, source stages, scores and timing summaries.
+- **Workbench** — Section rhythm, hero, cards, entries, timeline, mosaic and scroll reveal for the Workbench preset.

package/dist/article.css

@@ -0,0 +1,407 @@
+/* ==========================================================================
+   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-folio-article]`, which the `Article` component writes. Nothing
+   here leaks: a page that does not opt in is untouched.
+
+   Inside one, these rules BEAT a component's utilities, and that is the
+   mechanism the composition rests on rather than an accident. `styles/index.css`
+   imports this file unlayered while Tailwind's utilities sit in
+   `@layer utilities`, and an unlayered rule wins over a layered one whatever
+   either one's specificity is. So a `Markdown` paragraph — a `Text` carrying
+   `m-0` — gives its margin up to the rhythm below, which is the only reason
+   markdown dropped into an article reads as an article. The low specificity
+   here is for ordering these rules against EACH OTHER (see the `:is()` note
+   further down), not for losing to a utility.
+
+   A component that has to keep a property inside an article therefore cannot
+   do it with a class: it needs an inline style, or a tag this file does not
+   reach for — which is why `Diagram` draws its caption as a `<div>` rather than
+   as a `<figcaption>`.
+
+   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-folio-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-folio-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-folio-article] h1 {
+  font-size: var(--fs-title);
+  letter-spacing: -0.02em;
+}
+[data-folio-article] h2 {
+  font-size: var(--fs-heading);
+}
+[data-folio-article] h3 {
+  font-size: var(--fs-sub);
+}
+[data-folio-article] h4 {
+  font-size: var(--fs-item);
+}
+[data-folio-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-folio-article] p { margin: 0 }` is specificity 0,1,1 and outranks
+   `[data-folio-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-folio-article] :where(*) {
+  margin: 0;
+}
+[data-folio-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-folio-article] > :is(h1, h2, h3, h4, h5, h6) {
+  margin-block-start: 2.25em;
+}
+[data-folio-article] > :is(h1, h2, h3, h4, h5, h6) + * {
+  margin-block-start: 0.75em;
+}
+[data-folio-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-folio-article] p.lead {
+  font-size: var(--fs-item);
+  line-height: 1.6;
+  color: var(--ink);
+}
+
+/* ─── Inline ─────────────────────────────────────────────────────────────── */
+
+[data-folio-article] a {
+  color: var(--ink);
+  /* Extend the hit area without changing the surrounding line box. */
+  padding-block: max(0px, calc((var(--control-h-md) - 1.25em) / 2));
+  text-decoration: underline;
+  text-decoration-color: var(--rule-2);
+  text-underline-offset: 4px;
+  transition: text-decoration-color var(--fast) var(--ease);
+}
+[data-folio-article] a:hover {
+  text-decoration-color: var(--ink);
+}
+[data-folio-article] strong {
+  color: var(--ink);
+  font-weight: 500;
+}
+[data-folio-article] em {
+  font-style: italic;
+}
+[data-folio-article] mark {
+  background: var(--accent-muted);
+  color: var(--ink);
+  padding-inline: 0.2em;
+}
+[data-folio-article] abbr[title] {
+  text-decoration: underline dotted var(--rule-2);
+  text-underline-offset: 3px;
+}
+[data-folio-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-folio-article] :is(ul, ol) {
+  padding-inline-start: 1.4em;
+}
+[data-folio-article] :is(ul, ol) :is(ul, ol) {
+  margin-block-start: 0.4em;
+}
+[data-folio-article] li + li {
+  margin-block-start: 0.4em;
+}
+/* A paragraph or a fence nested inside a list item is still a block. */
+[data-folio-article] li > * + * {
+  margin-block-start: 0.6em;
+}
+[data-folio-article] li::marker {
+  color: var(--ink-3-aa);
+  font-size: 0.9em;
+}
+[data-folio-article] ul {
+  list-style: none;
+  padding-inline-start: 1.15em;
+}
+[data-folio-article] ul > li {
+  position: relative;
+}
+/* A hairline dash, which is the marker the rest of the system uses. */
+[data-folio-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-folio-article] ul > li:has(input[type='checkbox'])::before {
+  content: none;
+}
+[data-folio-article] li:has(input[type='checkbox']) {
+  padding-inline-start: 0;
+}
+[data-folio-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-folio-article] li:has(input[type='checkbox']) label {
+  display: inline;
+  cursor: default;
+}
+
+[data-folio-article] dt {
+  color: var(--ink);
+  font-weight: 500;
+}
+[data-folio-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-folio-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-folio-article] blockquote p + p {
+  margin-block-start: 0.6em;
+}
+[data-folio-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-folio-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-folio-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-folio-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-folio-article] :is(figure, table, .folio-wide) {
+  width: 100%;
+  max-width: none;
+}
+[data-folio-article] > figure {
+  margin-block-start: 2em;
+}
+[data-folio-article] :is(img, video) {
+  display: block;
+  max-width: 100%;
+  height: auto;
+  border-radius: var(--radius);
+}
+[data-folio-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-folio-article] .folio-table-scroll {
+  overflow-x: auto;
+  scrollbar-width: thin;
+  scrollbar-color: var(--rule-2) transparent;
+}
+[data-folio-article] table {
+  border-collapse: collapse;
+  font-size: 0.9375rem;
+  text-align: start;
+}
+[data-folio-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-folio-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-folio-article] :is(th, td):last-child {
+  padding-inline-end: 0;
+}
+
+[data-folio-article] > hr {
+  margin-block-start: 2.5em;
+}
+[data-folio-article] hr {
+  border: 0;
+  border-block-start: 1px solid var(--rule);
+}
+
+[data-folio-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-folio-article] math {
+  color: var(--ink);
+  font-size: 1.05em;
+}
+[data-folio-article] .folio-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-folio-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-folio-article] > .footnotes {
+  margin-block-start: 3em;
+}
+[data-folio-article] .footnotes {
+  padding-block-start: 1.5em;
+  border-block-start: 1px solid var(--rule);
+  font-size: 0.875rem;
+}
+[data-folio-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-folio-article] .footnote-backref {
+  /* The glyph is the affordance; a name is not. */
+  font-size: 0.9em;
+}