@echodial/deck 0.1.0

package/src/04-layout.css

@@ -0,0 +1,235 @@
+/* ==========================================================================
+   Deck — 04 Layout
+   Composable primitives. You lay out with about eight classes, not forty.
+   ========================================================================== */
+
+@layer deck.layout {
+
+  /* Centres content and caps it at --container, with the responsive page
+     gutter already applied. Nest one inside another and the inner one adds
+     a second gutter, so use .container-full instead. */
+  .container {
+    inline-size: 100%;
+    max-inline-size: var(--container, 76rem);
+    margin-inline: auto;
+    padding-inline: var(--space-gutter);
+  }
+  /* A single column of prose: about 70 characters at the body size,
+     which is inside the maximum line length WCAG recommends. */
+  .container-sm { --container: 40rem; }
+  /* An article with a rail, or a form. */
+  .container-md { --container: 56rem; }
+  /* The same 76rem as the bare .container, named. Use it when a page
+     should say which width it means rather than rely on the default. */
+  .container-lg { --container: 76rem; }
+  /* A wide dashboard or a data grid. */
+  .container-xl { --container: 90rem; }
+  /* Keeps the page gutter, drops the max width. This is what to nest
+     inside another container — a second .container would apply the
+     gutter twice. */
+  .container-full { --container: none; }
+
+  /* --- The spacing scale ----------------------------------------------------
+     Every spacing utility in Deck uses the same seven steps:
+
+       0    1        2       3       4      6        8
+       0    .25rem   .5rem   .75rem  1rem   1.5rem   2rem
+
+     .stack, .cluster, .gap-*, the padding utilities and the margin utilities
+     all implement exactly these, so a step that exists in one family exists in
+     all of them. There is deliberately no 5: at 1.25rem it is indistinguishable
+     from 4 and 6 in a real layout, and a half step between two neighbours is
+     the step people reach for when they are not sure, which is how .stack-5
+     came to be used in the demo when no such class existed.
+
+     The --space-* tokens keep their full range (0 through 24). Tokens are the
+     palette a component composes from; the utilities are the smaller set you
+     author markup with. Those are different jobs, so they are different sizes.
+     ---------------------------------------------------------------------- */
+
+  /* Vertical rhythm without margin collapse surprises */
+  .stack {
+    display: flex;
+    flex-direction: column;
+    gap: var(--gap, var(--space-4));
+  }
+  /* No gap. For two elements that must touch. */
+  .stack-0 { --gap: 0; }
+  /* A hairline. A label and the control it names, when the two read as
+     one thing. */
+  .stack-1 { --gap: var(--space-1); }
+  /* Tight vertical rhythm, for a label and its control or a title and its
+     subtitle. */
+  .stack-2 { --gap: var(--space-2); }
+  /* The default rhythm for related blocks inside a card or a section. */
+  .stack-3 { --gap: var(--space-3); }
+  /* The default, named. Same as .stack with no step class. */
+  .stack-4 { --gap: var(--space-4); }
+  /* Loose vertical rhythm, for separating whole sections of a page. */
+  .stack-6 { --gap: var(--space-6); }
+  /* Very loose, for whole sections of a page where .section is too much. */
+  .stack-8 { --gap: var(--space-8); }
+
+  /* Horizontal group that wraps instead of overflowing on a phone */
+  .cluster {
+    display: flex;
+    flex-wrap: wrap;
+    align-items: center;
+    gap: var(--gap, var(--space-3));
+  }
+  /* Kept as the readable name for step 2, which is what most clusters want */
+  .cluster-tight { --gap: var(--space-2); }
+  /* Packs the row against the end edge, which follows the writing
+     direction rather than always being the right. */
+  .cluster-end { justify-content: flex-end; }
+  /* Centres the row. */
+  .cluster-center { justify-content: center; }
+  /* First item to one end, last to the other. Beware of combining it
+     with wrapping: each line is justified separately, so a lone item on
+     the second line jumps to the far end and looks stranded. .bar with
+     .push is the predictable version. */
+  .cluster-between { justify-content: space-between; }
+
+  /* Push the last child away from the rest */
+  .bar {
+    display: flex;
+    align-items: center;
+    gap: var(--space-3);
+  }
+  .bar > .push { margin-inline-start: auto; }
+
+  /* Auto-fitting grid: no breakpoints needed, it responds to its own width */
+  .grid {
+    display: grid;
+    gap: var(--gap, var(--space-4));
+    grid-template-columns: repeat(auto-fit, minmax(min(var(--min, 17rem), 100%), 1fr));
+  }
+  /* Two-ish columns: an auto-fit grid with a 24rem floor. Identical in
+     effect to .grid-wide, but it writes grid-template-columns directly
+     rather than setting --min, so --min cannot adjust it afterwards.
+     Prefer .grid-wide. */
+  .grid-2 { grid-template-columns: repeat(auto-fit, minmax(min(24rem, 100%), 1fr)); }
+  /* Narrows the auto-fit column floor to 12rem, so the grid packs more
+     columns in before it wraps. */
+  .grid-tight { --min: 12rem; }
+  /* Widens the auto-fit column floor to 24rem, so the grid packs fewer,
+     wider columns before it wraps. For cards with a paragraph in them. */
+  .grid-wide { --min: 24rem; }
+  /* Exactly two equal columns at every width, including a phone. Only
+     for a count that is part of the meaning — a 2x2 comparison. It does
+     not reflow, so it does not satisfy the reflow criterion on its own. */
+  .grid-fixed-2 { grid-template-columns: 1fr 1fr; }
+  /* Exactly three equal columns at every width. See .grid-fixed-2. */
+  .grid-fixed-3 { grid-template-columns: repeat(3, 1fr); }
+  /* Exactly four equal columns at every width. On a phone that is four
+     70px columns; reach for .grid with a --min instead. */
+  .grid-fixed-4 { grid-template-columns: repeat(4, 1fr); }
+
+  /* Content + rail. Collapses to one column below the width it needs. */
+  .split {
+    display: grid;
+    gap: var(--gap, var(--space-6));
+    grid-template-columns: 1fr;
+  }
+  /* A grid item's min-inline-size is auto, so a child that cannot shrink — a
+     form row, a wide table, a long code block — makes the whole column wider
+     than its track and pushes the page sideways. This is the single most
+     common grid bug there is; the two-column form in the demo overflowed a
+     375px viewport by 16px until this line existed. */
+  .split > * { min-inline-size: 0; }
+  @media (min-width: 64rem) {
+    .split { grid-template-columns: minmax(0, 1fr) var(--rail, 20rem); }
+    /* Puts the rail on the starting edge without touching markup order, so
+       the main column stays first for a screen reader and for the keyboard.
+       Use it for supplementary navigation; not for a rail holding the first
+       thing a reader needs. */
+    .split-rail-start { grid-template-columns: var(--rail, 20rem) minmax(0, 1fr); }
+  }
+
+  /* Center a thing with a max width and no side effects */
+  .center {
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    text-align: center;
+    gap: var(--gap, var(--space-4));
+  }
+
+  /* Vertical page rhythm: a block of --space-section, which is a clamp that
+     grows with the viewport. For spacing inside a component reach for
+     .stack instead. */
+  .section { padding-block: var(--space-section); }
+
+  /* Everything stays on one line and scrolls sideways — cards, chips, dates */
+  .scroller {
+    display: flex;
+    gap: var(--gap, var(--space-3));
+    overflow-x: auto;
+    overscroll-behavior-inline: contain;
+    scroll-snap-type: x proximity;
+    scrollbar-width: none;
+    padding-block-end: var(--space-2);
+    margin-inline: calc(var(--space-gutter) * -1);
+    padding-inline: var(--space-gutter);
+  }
+  .scroller::-webkit-scrollbar { display: none; }
+  .scroller > * { scroll-snap-align: start; flex: 0 0 auto; }
+
+  /* A sticky header. Where scroll-state container queries are supported
+     the blur and shadow live on an ::after that is transparent until the
+     header actually sticks, so in flow it looks like part of the page.
+     The treatment rides on a pseudo-element because a scroll-state
+     container can style its descendants but not itself. */
+  .sticky-top {
+    position: sticky;
+    inset-block-start: 0;
+    z-index: var(--z-sticky);
+    background: color-mix(in oklab, var(--bg) 82%, transparent);
+    backdrop-filter: saturate(1.6) blur(12px);
+    -webkit-backdrop-filter: saturate(1.6) blur(12px);
+  }
+
+  /* Sitting in flow it needs no treatment at all; it earns the blur and the
+     shadow at the moment it actually sticks. A scroll-state container cannot
+     style itself, so the treatment rides on ::after, which is inside it. */
+  @supports (container-type: scroll-state) {
+    .sticky-top {
+      container-type: scroll-state;
+      background: none;
+      backdrop-filter: none;
+      -webkit-backdrop-filter: none;
+    }
+    .sticky-top::after {
+      content: "";
+      position: absolute;
+      inset: 0;
+      z-index: -1;
+      opacity: 0;
+      background: color-mix(in oklab, var(--bg) 82%, transparent);
+      backdrop-filter: saturate(1.6) blur(12px);
+      -webkit-backdrop-filter: saturate(1.6) blur(12px);
+      transition: opacity var(--dur-2) var(--ease-out);
+    }
+    @container scroll-state(stuck: block-start) {
+      .sticky-top::after { opacity: 1; box-shadow: var(--shadow-2); }
+    }
+  }
+
+  /* Header, content, footer in a 100dvh grid whose middle row takes the
+     remaining height — the sticky footer, without the hacks. dvh rather
+     than vh so it tracks a phone browser hiding its chrome. It expects
+     exactly three children. */
+  .app-shell {
+    display: grid;
+    min-block-size: 100dvh;
+    grid-template-rows: auto 1fr auto;
+  }
+
+  /* Aspect boxes for media */
+  .ratio-16x9 { aspect-ratio: 16 / 9; object-fit: cover; inline-size: 100%; }
+  .ratio-4x3  { aspect-ratio: 4 / 3;  object-fit: cover; inline-size: 100%; }
+  .ratio-1x1  { aspect-ratio: 1;      object-fit: cover; inline-size: 100%; }
+
+  /* Container queries: components respond to their slot, not the viewport */
+  .cq { container-type: inline-size; }
+}

package/src/05-buttons.css

@@ -0,0 +1,210 @@
+/* ==========================================================================
+   Deck — 05 Buttons
+   ========================================================================== */
+
+@layer deck.components {
+
+  .btn {
+    --btn-bg: var(--surface);
+    --btn-text: var(--text);
+    --btn-border: var(--line-strong);
+    --btn-shadow: var(--shadow-1);
+
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    gap: var(--space-2);
+    block-size: var(--control-h);
+    min-inline-size: var(--control-h);
+    padding-inline: var(--space-4);
+    border: 1px solid var(--btn-border);
+    border-radius: var(--r-sm);
+    background: var(--btn-bg);
+    color: var(--btn-text);
+    box-shadow: var(--btn-shadow);
+    font-size: var(--text-base);
+    font-weight: 560;
+    line-height: 1;
+    letter-spacing: -.008em;
+    white-space: nowrap;
+    text-decoration: none;
+    cursor: pointer;
+    user-select: none;
+    -webkit-tap-highlight-color: transparent;
+    touch-action: manipulation;
+    transition: background-color var(--dur-1) var(--ease-out),
+                border-color var(--dur-1) var(--ease-out),
+                color var(--dur-1) var(--ease-out),
+                box-shadow var(--dur-1) var(--ease-out),
+                translate var(--dur-1) var(--ease-out);
+  }
+
+  /* Every button clears the 44px touch target even when it looks smaller */
+  .btn { position: relative; }
+  .btn::before {
+    content: "";
+    position: absolute;
+    inset-block-start: 50%;
+    inset-inline-start: 50%;
+    translate: -50% -50%;
+    inline-size: 100%;
+    block-size: 100%;
+    min-inline-size: var(--tap);
+    min-block-size: var(--tap);
+  }
+
+  .btn:hover { background: var(--surface-hover); border-color: var(--ink-400); }
+  .btn:active { translate: 0 1px; box-shadow: none; }
+  .btn:focus-visible { outline: 2px solid var(--focus); outline-offset: 2px; }
+
+  /* Styles a link or non-form element as disabled. It cannot stop a click
+     the way the disabled attribute does, so add aria-disabled="true" and
+     remove the href if it must not be followed. */
+  .btn[disabled], .btn[aria-disabled="true"], .btn.is-disabled {
+    opacity: .5;
+    cursor: not-allowed;
+    pointer-events: none;
+  }
+
+  /* --- Variants ----------------------------------------------------------- */
+  /* The one important action in a view. Solid brand fill; use exactly one
+     per screen so it keeps meaning something. */
+  .btn-primary {
+    --btn-bg: var(--brand-600);
+    --btn-text: var(--text-on-brand);
+    --btn-border: transparent;
+    --btn-shadow: var(--shadow-2), var(--shadow-inset);
+  }
+  .btn-primary:hover { --btn-bg: var(--brand-700); border-color: transparent; background: var(--brand-700); }
+
+  /* A secondary emphasis colour, for upsells and highlights. */
+  .btn-accent {
+    --btn-bg: var(--accent-500);
+    --btn-text: var(--text-on-accent);
+    --btn-border: transparent;
+    --btn-shadow: var(--shadow-2), var(--shadow-inset);
+  }
+  .btn-accent:hover { background: oklch(from var(--accent-500) calc(l - .05) c h); border-color: transparent; }
+
+  /* Destructive and irreversible. Pair it with a confirmation. */
+  .btn-danger {
+    --btn-bg: var(--bad-600);
+    --btn-text: var(--text-on-bad);
+    --btn-border: transparent;
+    --btn-shadow: var(--shadow-2), var(--shadow-inset);
+  }
+  .btn-danger:hover { background: var(--bad-700); border-color: transparent; }
+
+  /* Tinted, low weight. Good for an action repeated down a list. */
+  .btn-soft {
+    --btn-bg: var(--brand-soft);
+    --btn-text: var(--brand-soft-text);
+    --btn-border: transparent;
+    --btn-shadow: none;
+  }
+  .btn-soft:hover { background: color-mix(in oklab, var(--brand-soft) 80%, var(--brand-300)); border-color: transparent; }
+
+  /* No border or background until hover. For toolbars and dense rows where
+     seven bordered buttons would be noise. */
+  .btn-ghost {
+    --btn-bg: transparent;
+    --btn-border: transparent;
+    --btn-shadow: none;
+  }
+  .btn-ghost:hover { background: var(--surface-hover); border-color: transparent; }
+
+  /* Brand-coloured border, transparent fill. */
+  .btn-outline {
+    --btn-bg: transparent;
+    --btn-text: var(--brand);
+    --btn-border: color-mix(in oklab, var(--brand) 45%, transparent);
+    --btn-shadow: none;
+  }
+  .btn-outline:hover { background: var(--brand-soft); border-color: var(--brand); }
+
+  /* Looks like a link, behaves like a button. Only for a real <button>
+     that has to sit in a row of links — on an anchor it adds a touch
+     target, a ring offset and nowrap to something that wanted none of them. */
+  .btn-link {
+    --btn-bg: transparent;
+    --btn-border: transparent;
+    --btn-shadow: none;
+    --btn-text: var(--brand);
+    padding-inline: var(--space-1);
+    block-size: auto;
+  }
+  .btn-link:hover { background: none; border-color: transparent; text-decoration: underline; }
+
+  /* --- Sizes -------------------------------------------------------------- */
+  /* The 34px size. Still clears the 44px touch target, because the target
+     is a pseudo-element rather than the box. */
+  .btn-sm {
+    block-size: var(--control-h-sm);
+    padding-inline: var(--space-3);
+    font-size: var(--text-sm);
+    border-radius: var(--r-xs);
+    gap: var(--space-1);
+  }
+  /* The large size, from --control-h-lg. */
+  .btn-lg {
+    block-size: var(--control-h-lg);
+    padding-inline: var(--space-6);
+    font-size: var(--text-md);
+    font-weight: 600;
+  }
+  /* Full width. For a phone, or the primary action at the end of a form. */
+  .btn-block { inline-size: 100%; }
+
+  /* Square, icon-only button. It has no text, so it needs an aria-label. */
+  .btn-icon { padding-inline: 0; inline-size: var(--control-h); }
+  .btn-icon.btn-sm { inline-size: var(--control-h-sm); }
+  .btn-icon.btn-lg { inline-size: var(--control-h-lg); }
+  /* A fully rounded button, usually paired with .btn-icon. */
+  .btn-round { border-radius: var(--r-full); }
+
+  /* --- Group -------------------------------------------------------------- */
+  /* Buttons joined into one control, with the inner radii and the doubled
+     border between them removed. Logical radii, so it mirrors under RTL. */
+  .btn-group { display: inline-flex; }
+  .btn-group > .btn { border-radius: 0; box-shadow: none; }
+  .btn-group > .btn:first-child { border-start-start-radius: var(--r-sm); border-end-start-radius: var(--r-sm); }
+  .btn-group > .btn:last-child  { border-start-end-radius: var(--r-sm); border-end-end-radius: var(--r-sm); }
+  .btn-group > .btn + .btn { margin-inline-start: -1px; }
+  .btn-group > .btn:hover, .btn-group > .btn:focus-visible { z-index: 1; }
+
+  /* --- Loading ------------------------------------------------------------ */
+  .btn.is-loading { color: transparent; pointer-events: none; }
+  .btn.is-loading::after {
+    content: "";
+    position: absolute;
+    inline-size: 1em;
+    block-size: 1em;
+    border: 2px solid color-mix(in oklab, var(--btn-text) 30%, transparent);
+    border-block-start-color: var(--btn-text);
+    border-radius: var(--r-full);
+    animation: dk-spin .62s linear infinite;
+  }
+
+  @keyframes dk-spin { to { rotate: 360deg; } }
+
+  /* Floating action button, parked above the tab bar and the notch */
+  .fab {
+    position: fixed;
+    inset-block-end: calc(var(--space-5) + env(safe-area-inset-bottom));
+    inset-inline-end: var(--space-5);
+    z-index: var(--z-nav);
+    inline-size: 56px;
+    block-size: 56px;
+    border-radius: var(--r-full);
+    background: var(--brand-600);
+    color: var(--text-on-brand);
+    box-shadow: var(--shadow-4);
+    display: grid;
+    place-items: center;
+    cursor: pointer;
+    transition: scale var(--dur-2) var(--ease-spring), background-color var(--dur-1) var(--ease-out);
+  }
+  .fab:hover { background: var(--brand-700); scale: 1.04; }
+  .fab:active { scale: .96; }
+  body:has(.tabbar) .fab { inset-block-end: calc(var(--space-4) + var(--tap) + var(--space-3) + env(safe-area-inset-bottom)); }
+}