@cahyo-dimas/freeday 1.18.0 → 1.21.0

package/dist/freeday.bundle.css

@@ -177,6 +177,9 @@
   --focus-ring: var(--azure-600);
   --focus-ring-width: 2px;
 }
+/* The SYSTEM default stays root-scoped: it is a statement about the document, and dropping :root
+ * here would match every element that is not itself [data-theme="light"] — which would re-darken
+ * the children of a light panel, since they carry no attribute of their own. */
 @media (prefers-color-scheme: dark) {
   :root:not([data-theme="light"]) {
   --shadow-1: 0 1px 2px rgba(0,0,0,.4);
@@ -235,7 +238,13 @@
   --focus-ring: var(--azure-400);
   }
 }
-:root[data-theme="dark"] {
+/* The two EXPLICIT opt-ins are deliberately NOT scoped to :root, for the same reason as density
+ * below: these are inheriting custom properties, so data-theme on any ancestor re-themes just that
+ * subtree — a dark brand panel beside a light form is an ordinary layout, and it should not require
+ * re-colouring each component by hand. The root still matches, so data-theme on <html> is unchanged.
+ * Both keep the same specificity (0,1,0) as :root and come after it, so they still win there; and
+ * --light after --dark means a light island inside a dark region wins in turn. */
+[data-theme="dark"] {
   --shadow-1: 0 1px 2px rgba(0,0,0,.4);
   --shadow-2: 0 2px 6px rgba(0,0,0,.45);
   --shadow-3: 0 6px 20px -2px rgba(0,0,0,.6),0 1px 3px rgba(0,0,0,.5);
@@ -291,7 +300,7 @@
   --chart-tick: var(--slate-600);
   --focus-ring: var(--azure-400);
 }
-:root[data-theme="light"] {
+[data-theme="light"] {
   --shadow-1: 0 1px 2px rgba(16,14,30,.06);
   --shadow-2: 0 2px 6px rgba(16,14,30,.07),0 1px 2px rgba(16,14,30,.05);
   --shadow-3: 0 4px 16px -2px rgba(16,14,30,.14),0 1px 3px rgba(16,14,30,.10);
@@ -347,7 +356,11 @@
   --chart-tick: var(--slate-400);
   --focus-ring: var(--azure-600);
 }
-:root[data-density="compact"] {
+/* Density is deliberately NOT scoped to :root. These are custom properties, so they inherit —
+ * putting the attribute on any ancestor (a route wrapper, one section) densifies just that
+ * subtree, which is how density is actually decided: per screen, not per app. The root still
+ * matches, so setting data-density on the html element keeps working exactly as before. */
+[data-density="compact"] {
   --space-3: 0.625rem;
   --space-4: 0.75rem;
   --space-5: 1rem;
@@ -372,6 +385,21 @@ h1, h2, h3, h4 { font-family: var(--font-display); font-weight: var(--weight-bol
 a { color: var(--color-primary); }
 :focus-visible { outline: var(--focus-ring-width) solid var(--focus-ring); outline-offset: var(--focus-ring-width); border-radius: var(--radius-xs); }
 :where(button, input, select, textarea) { font: inherit; }
+/* Hidden from sight, kept for assistive tech. `clip` hides PAINTING, not LAYOUT: the box still
+ * has a position, and because it is position:absolute its containing block is the nearest
+ * POSITIONED ancestor — with none, the initial containing block (the document itself).
+ *
+ * That matters, because `overflow` only clips a descendant whose containing block is inside the
+ * overflow box. So a hidden span in a horizontally scrolling table (the kit's own recommended way
+ * to name an icon button) parks at its static position — possibly thousands of px to the right —
+ * and drags the whole DOCUMENT sideways: invisible, and immune to `overflow-x:hidden` on every
+ * wrapper. Measured before the fix: 1351px of phantom page scroll from 11 spans.
+ *
+ * The fix is not here — it is on the containers: every clipping/scrolling container in the kit
+ * that holds consumer markup declares `position:relative` so it becomes the containing block for
+ * its own out-of-flow content (see test/css.test.mjs, which will not let a new one skip it).
+ * Note the measurement trap: documentElement.scrollWidth sees it, body.scrollWidth does not —
+ * the honest check is `window.scrollTo(9999, 0)` then reading `window.scrollX`. */
 .fdy-visually-hidden { position: absolute !important; width: 1px; height: 1px; padding: 0; margin: -1px; overflow: hidden; clip: rect(0, 0, 0, 0); white-space: nowrap; border: 0; }
 /* Opt-in list reset. base.css is intentionally a *light* reset — it does NOT strip list/paragraph
  * margins (see the kit's own list components, which each reset themselves). If you run a utility
@@ -383,7 +411,11 @@ a { color: var(--color-primary); }
 }
 
 /* Freeday — Accordion (native <details>/<summary>, zero-JS) */
-.fdy-accordion{border:var(--bw) solid var(--color-border);border-radius:var(--radius-lg);overflow:hidden;background:var(--color-surface);}
+/* position:relative — containing block for out-of-flow panel content (see base.css). NOT redundant
+   with the panel's reveal animation: that animation gives the panel a transform (which happens to
+   make it a containing block too), but it lives behind prefers-reduced-motion:no-preference — so
+   without this line the escape bug appears ONLY for readers who asked for reduced motion. */
+.fdy-accordion{position:relative;border:var(--bw) solid var(--color-border);border-radius:var(--radius-lg);overflow:hidden;background:var(--color-surface);}
 .fdy-accordion__item + .fdy-accordion__item{border-top:var(--bw) solid var(--color-border);}
 .fdy-accordion__item > summary{list-style:none;cursor:pointer;display:flex;align-items:center;gap:var(--space-3);padding:var(--space-3) var(--space-4);font-weight:var(--weight-medium);color:var(--color-text);}
 .fdy-accordion__item > summary::-webkit-details-marker{display:none;}
@@ -669,7 +701,9 @@ a { color: var(--color-primary); }
 .fdy-fab--accent{background:linear-gradient(180deg,var(--color-accent),color-mix(in srgb,#000 10%,var(--color-accent)));color:var(--color-on-accent);}
 
 /* Freeday — Card */
-.fdy-card{background:var(--color-surface);border:var(--bw) solid var(--color-border);border-radius:var(--radius-lg);overflow:hidden;box-shadow:var(--shadow-lift);transition:box-shadow var(--dur-base) var(--ease-standard),transform var(--dur-base) var(--ease-standard);}
+/* position:relative — containing block for out-of-flow card content (see base.css); it also gives
+   consumers the anchor a corner ribbon/badge needs. */
+.fdy-card{position:relative;background:var(--color-surface);border:var(--bw) solid var(--color-border);border-radius:var(--radius-lg);overflow:hidden;box-shadow:var(--shadow-lift);transition:box-shadow var(--dur-base) var(--ease-standard),transform var(--dur-base) var(--ease-standard);}
 .fdy-card--elevated{box-shadow:var(--shadow-lift-hover);}
 .fdy-card--interactive{cursor:pointer;}
 .fdy-card--interactive:hover{box-shadow:var(--shadow-lift-hover);transform:translateY(-3px);}
@@ -680,6 +714,10 @@ a { color: var(--color-primary); }
  * announced — reset the UA button box. Note: it does NOT reset background/border, because
  * .fdy-card already sets its own surface + border (resetting them here would strip the card). */
 .fdy-card--button{display:block;width:100%;text-align:inherit;color:inherit;appearance:none;-webkit-appearance:none;}
+/* Disabled card-as-control — same contract as .fdy-list__row--button: dim + not-allowed, and the
+   --interactive lift is withdrawn so a refusing control stops answering the pointer. */
+.fdy-card--button:disabled,.fdy-card--button[aria-disabled="true"],.fdy-card--interactive[aria-disabled="true"]{opacity:.5;cursor:not-allowed;}
+.fdy-card--interactive:disabled:hover,.fdy-card--interactive[aria-disabled="true"]:hover{box-shadow:var(--shadow-lift);transform:none;}
 .fdy-card__body{padding:var(--space-5);}
 .fdy-card__title{font-family:var(--font-display);font-size:var(--text-lg);font-weight:var(--weight-semibold);letter-spacing:var(--tracking-tight);color:var(--color-text);margin:0 0 var(--space-1);}
 .fdy-card__desc{font-size:var(--text-sm);color:var(--color-text-muted);margin:0;line-height:var(--leading-normal);}
@@ -687,7 +725,10 @@ a { color: var(--color-primary); }
 
 /* Freeday — Carousel (scroll-snap track + arrows + dots). Enhanced by freeday-carousel.js. */
 .fdy-carousel{position:relative;}
-.fdy-carousel__viewport{display:flex;overflow-x:auto;scroll-snap-type:x mandatory;scroll-behavior:smooth;border-radius:var(--radius-lg);scrollbar-width:none;-ms-overflow-style:none;}
+/* position:relative — the arrows are positioned against .fdy-carousel (the parent), so this only
+   catches out-of-flow content inside the SLIDES, which would otherwise escape the viewport
+   entirely and scroll the page by one slide-offset per slide (see base.css). */
+.fdy-carousel__viewport{position:relative;display:flex;overflow-x:auto;scroll-snap-type:x mandatory;scroll-behavior:smooth;border-radius:var(--radius-lg);scrollbar-width:none;-ms-overflow-style:none;}
 .fdy-carousel__viewport::-webkit-scrollbar{display:none;}
 .fdy-carousel__slide{flex:0 0 100%;min-width:0;scroll-snap-align:center;}
 .fdy-carousel__arrow{position:absolute;top:50%;transform:translateY(-50%);z-index:2;display:inline-flex;align-items:center;justify-content:center;width:2.25rem;height:2.25rem;border:0;border-radius:var(--radius-full);background:color-mix(in srgb,var(--color-surface) 86%,transparent);color:var(--color-text);box-shadow:var(--shadow-2);cursor:pointer;transition:background var(--dur-fast) var(--ease-standard);}
@@ -1184,6 +1225,43 @@ fieldset.fdy-field>legend{padding:0;float:none;}
 /* Freeday — Keyboard key */
 .fdy-kbd{display:inline-flex;align-items:center;justify-content:center;min-width:1.5rem;height:1.5rem;padding:0 var(--space-2);font-family:var(--font-mono);font-size:var(--text-xs);color:var(--color-text);background:var(--color-surface-2);border:var(--bw) solid var(--color-border-strong);border-bottom-width:2px;border-radius:var(--radius-sm);}
 
+/* Freeday — List: the FLAT row container.
+ *
+ * USAGE.md §3 puts list rows among the surfaces that should be flat, but until now the only
+ * container the kit shipped was .fdy-card — which carries --shadow-lift (a real 34px lift). A
+ * responsive table that becomes a list below `md` therefore had to choose between a stack of
+ * shadowed cards (against the doctrine) or a hand-built box, which needs a colour and so escapes
+ * the token system. This is that missing container: one flat surface, hairline dividers, no shadow.
+ *
+ * Not to be confused with .fdy-list-reset (base.css), which only strips UA bullets/indent.
+ * Works on <ul>/<ol> (list-style is reset here) or on plain <div>s. */
+/* position:relative — containing block for out-of-flow row content (see base.css). */
+.fdy-list{position:relative;list-style:none;margin:0;padding:0;background:var(--color-surface);border:var(--bw) solid var(--color-border);border-radius:var(--radius-lg);overflow:hidden;}
+.fdy-list__row{display:flex;align-items:center;gap:var(--space-3);padding:var(--space-4) var(--space-5);min-width:0;}
+/* Divider between rows. Two shapes are supported and both are load-bearing: rows as direct children
+ * of the list, and rows wrapped in <li> (the semantic shape, where the ADJACENT siblings are the
+ * <li>s — a bare `.fdy-list__row + .fdy-list__row` silently matches nothing there). */
+.fdy-list__row + .fdy-list__row,
+.fdy-list > * + * > .fdy-list__row{border-top:var(--bw) solid var(--color-border-muted);}
+/* A row that is itself the control: render it as <button>/<a> and the UA box is reset without
+ * touching the list surface (same contract as .fdy-card--button). */
+.fdy-list__row--button{width:100%;text-align:inherit;color:inherit;font:inherit;background:none;border:0;appearance:none;-webkit-appearance:none;cursor:pointer;}
+.fdy-list__row--button:hover,.fdy-list__row--interactive:hover{background:var(--color-surface-2);}
+.fdy-list__row--button:focus-visible{outline:none;box-shadow:inset 0 0 0 2px var(--color-primary);}
+.fdy-list__row--interactive{cursor:pointer;}
+/* Disabled row. The reset above adopts the UA button box, but not its disabled state — so a row
+   disabled mid-flight (a redirect in progress, say) kept lighting up and kept a pointer cursor:
+   a control answering the pointer while refusing input. Same contract as every other disabled
+   control in the kit (dim + not-allowed), hover withdrawn, both the native and the aria- form. */
+.fdy-list__row--button:disabled,.fdy-list__row--button[aria-disabled="true"],.fdy-list__row--interactive[aria-disabled="true"]{opacity:.5;cursor:not-allowed;}
+.fdy-list__row--button:disabled:hover,.fdy-list__row--button[aria-disabled="true"]:hover,.fdy-list__row--interactive[aria-disabled="true"]:hover{background:none;}
+/* Row internals: a title/meta stack that truncates, and a trailing slot pinned right. */
+.fdy-list__main{display:flex;flex-direction:column;gap:var(--space-1);min-width:0;flex:1;}
+.fdy-list__title{font-weight:var(--weight-medium);color:var(--color-text);overflow:hidden;text-overflow:ellipsis;white-space:nowrap;}
+.fdy-list__meta{font-size:var(--text-sm);color:var(--color-text-muted);display:flex;align-items:center;gap:var(--space-2);flex-wrap:wrap;}
+.fdy-list__aside{flex:none;display:flex;align-items:center;gap:var(--space-2);}
+/* Density: rows tighten with the rest of the kit (--space-* mid-range steps under compact). */
+
 /* Freeday — Menu (action popup) + Split button. Enhanced by freeday-menu.js. */
 .fdy-menu-wrap{position:relative;display:inline-flex;}
 .fdy-menu{position:absolute;top:calc(100% + var(--space-1));left:0;z-index:130;min-width:11rem;margin:0;padding:var(--space-1);list-style:none;background:var(--color-surface);color:var(--color-text);border:var(--bw) solid var(--color-border-strong);border-radius:var(--radius-md);box-shadow:var(--shadow-3);}
@@ -1361,7 +1439,10 @@ fieldset.fdy-field>legend{padding:0;float:none;}
 .fdy-step-nav{display:flex;justify-content:space-between;gap:var(--space-2);margin-top:var(--space-5);}
 
 /* Freeday — Table */
-.fdy-table-wrap{overflow-x:auto;border:var(--bw) solid var(--color-border);border-radius:var(--radius-lg);box-shadow:var(--shadow-1);background:var(--color-surface);}
+/* position:relative on every scroller/clipper — it makes the box the containing block for its own
+   absolutely positioned content (.fdy-visually-hidden above all), which `overflow` alone does NOT
+   clip. Without it a hidden label in a wide table scrolls the whole page. See base.css. */
+.fdy-table-wrap{position:relative;overflow-x:auto;border:var(--bw) solid var(--color-border);border-radius:var(--radius-lg);box-shadow:var(--shadow-1);background:var(--color-surface);}
 .fdy-table{width:100%;border-collapse:collapse;font-size:var(--text-sm);}
 .fdy-table caption{text-align:left;padding:var(--space-3) var(--space-4);font-weight:var(--weight-semibold);color:var(--color-text);}
 .fdy-table th{text-align:left;padding:var(--space-3) var(--space-4);font-size:var(--text-xs);font-weight:var(--weight-semibold);text-transform:uppercase;letter-spacing:var(--tracking-wide);color:var(--color-text-muted);background:var(--color-surface-2);border-bottom:var(--bw) solid var(--color-border);white-space:nowrap;}
@@ -1398,7 +1479,7 @@ fieldset.fdy-field>legend{padding:0;float:none;}
 
 /* Data-table shell (toolbar + scroll + footer stay put while the table scrolls) */
 .fdy-datatable{border:var(--bw) solid var(--color-border);border-radius:var(--radius-lg);box-shadow:var(--shadow-1);background:var(--color-surface);overflow:hidden;}
-.fdy-table-scroll{overflow-x:auto;}
+.fdy-table-scroll{position:relative;overflow-x:auto;}
 .fdy-table-toolbar{display:flex;align-items:center;gap:var(--space-3);flex-wrap:wrap;padding:var(--space-3) var(--space-4);border-bottom:var(--bw) solid var(--color-border);}
 .fdy-table-toolbar__search{max-width:18rem;}
 .fdy-table-toolbar__spacer{flex:1;}
@@ -1431,7 +1512,8 @@ fieldset.fdy-field>legend{padding:0;float:none;}
 .fdy-table-bulkbar__actions{display:flex;gap:var(--space-2);}
 
 /* Freeday — Tabs (WAI-ARIA APG) */
-.fdy-tabs__list{display:flex;gap:var(--space-1);border-bottom:var(--bw) solid var(--color-border);overflow-x:auto;}
+/* position:relative — containing block for out-of-flow content in the tabs (see base.css). */
+.fdy-tabs__list{position:relative;display:flex;gap:var(--space-1);border-bottom:var(--bw) solid var(--color-border);overflow-x:auto;}
 .fdy-tabs__tab{appearance:none;border:0;background:transparent;cursor:pointer;white-space:nowrap;font-family:var(--font-body);font-size:var(--text-sm);font-weight:var(--weight-medium);color:var(--color-text-muted);padding:var(--space-3) var(--space-4);border-bottom:2px solid transparent;margin-bottom:-1px;transition:color var(--dur-fast) var(--ease-standard),border-color var(--dur-fast) var(--ease-standard);}
 .fdy-tabs__tab:hover{color:var(--color-text);}
 .fdy-tabs__tab:disabled,.fdy-tabs__tab[aria-disabled="true"]{opacity:.5;cursor:not-allowed;color:var(--color-text-muted);}

package/dist/freeday.css

@@ -15,6 +15,21 @@ h1, h2, h3, h4 { font-family: var(--font-display); font-weight: var(--weight-bol
 a { color: var(--color-primary); }
 :focus-visible { outline: var(--focus-ring-width) solid var(--focus-ring); outline-offset: var(--focus-ring-width); border-radius: var(--radius-xs); }
 :where(button, input, select, textarea) { font: inherit; }
+/* Hidden from sight, kept for assistive tech. `clip` hides PAINTING, not LAYOUT: the box still
+ * has a position, and because it is position:absolute its containing block is the nearest
+ * POSITIONED ancestor — with none, the initial containing block (the document itself).
+ *
+ * That matters, because `overflow` only clips a descendant whose containing block is inside the
+ * overflow box. So a hidden span in a horizontally scrolling table (the kit's own recommended way
+ * to name an icon button) parks at its static position — possibly thousands of px to the right —
+ * and drags the whole DOCUMENT sideways: invisible, and immune to `overflow-x:hidden` on every
+ * wrapper. Measured before the fix: 1351px of phantom page scroll from 11 spans.
+ *
+ * The fix is not here — it is on the containers: every clipping/scrolling container in the kit
+ * that holds consumer markup declares `position:relative` so it becomes the containing block for
+ * its own out-of-flow content (see test/css.test.mjs, which will not let a new one skip it).
+ * Note the measurement trap: documentElement.scrollWidth sees it, body.scrollWidth does not —
+ * the honest check is `window.scrollTo(9999, 0)` then reading `window.scrollX`. */
 .fdy-visually-hidden { position: absolute !important; width: 1px; height: 1px; padding: 0; margin: -1px; overflow: hidden; clip: rect(0, 0, 0, 0); white-space: nowrap; border: 0; }
 /* Opt-in list reset. base.css is intentionally a *light* reset — it does NOT strip list/paragraph
  * margins (see the kit's own list components, which each reset themselves). If you run a utility
@@ -26,7 +41,11 @@ a { color: var(--color-primary); }
 }
 
 /* Freeday — Accordion (native <details>/<summary>, zero-JS) */
-.fdy-accordion{border:var(--bw) solid var(--color-border);border-radius:var(--radius-lg);overflow:hidden;background:var(--color-surface);}
+/* position:relative — containing block for out-of-flow panel content (see base.css). NOT redundant
+   with the panel's reveal animation: that animation gives the panel a transform (which happens to
+   make it a containing block too), but it lives behind prefers-reduced-motion:no-preference — so
+   without this line the escape bug appears ONLY for readers who asked for reduced motion. */
+.fdy-accordion{position:relative;border:var(--bw) solid var(--color-border);border-radius:var(--radius-lg);overflow:hidden;background:var(--color-surface);}
 .fdy-accordion__item + .fdy-accordion__item{border-top:var(--bw) solid var(--color-border);}
 .fdy-accordion__item > summary{list-style:none;cursor:pointer;display:flex;align-items:center;gap:var(--space-3);padding:var(--space-3) var(--space-4);font-weight:var(--weight-medium);color:var(--color-text);}
 .fdy-accordion__item > summary::-webkit-details-marker{display:none;}
@@ -312,7 +331,9 @@ a { color: var(--color-primary); }
 .fdy-fab--accent{background:linear-gradient(180deg,var(--color-accent),color-mix(in srgb,#000 10%,var(--color-accent)));color:var(--color-on-accent);}
 
 /* Freeday — Card */
-.fdy-card{background:var(--color-surface);border:var(--bw) solid var(--color-border);border-radius:var(--radius-lg);overflow:hidden;box-shadow:var(--shadow-lift);transition:box-shadow var(--dur-base) var(--ease-standard),transform var(--dur-base) var(--ease-standard);}
+/* position:relative — containing block for out-of-flow card content (see base.css); it also gives
+   consumers the anchor a corner ribbon/badge needs. */
+.fdy-card{position:relative;background:var(--color-surface);border:var(--bw) solid var(--color-border);border-radius:var(--radius-lg);overflow:hidden;box-shadow:var(--shadow-lift);transition:box-shadow var(--dur-base) var(--ease-standard),transform var(--dur-base) var(--ease-standard);}
 .fdy-card--elevated{box-shadow:var(--shadow-lift-hover);}
 .fdy-card--interactive{cursor:pointer;}
 .fdy-card--interactive:hover{box-shadow:var(--shadow-lift-hover);transform:translateY(-3px);}
@@ -323,6 +344,10 @@ a { color: var(--color-primary); }
  * announced — reset the UA button box. Note: it does NOT reset background/border, because
  * .fdy-card already sets its own surface + border (resetting them here would strip the card). */
 .fdy-card--button{display:block;width:100%;text-align:inherit;color:inherit;appearance:none;-webkit-appearance:none;}
+/* Disabled card-as-control — same contract as .fdy-list__row--button: dim + not-allowed, and the
+   --interactive lift is withdrawn so a refusing control stops answering the pointer. */
+.fdy-card--button:disabled,.fdy-card--button[aria-disabled="true"],.fdy-card--interactive[aria-disabled="true"]{opacity:.5;cursor:not-allowed;}
+.fdy-card--interactive:disabled:hover,.fdy-card--interactive[aria-disabled="true"]:hover{box-shadow:var(--shadow-lift);transform:none;}
 .fdy-card__body{padding:var(--space-5);}
 .fdy-card__title{font-family:var(--font-display);font-size:var(--text-lg);font-weight:var(--weight-semibold);letter-spacing:var(--tracking-tight);color:var(--color-text);margin:0 0 var(--space-1);}
 .fdy-card__desc{font-size:var(--text-sm);color:var(--color-text-muted);margin:0;line-height:var(--leading-normal);}
@@ -330,7 +355,10 @@ a { color: var(--color-primary); }
 
 /* Freeday — Carousel (scroll-snap track + arrows + dots). Enhanced by freeday-carousel.js. */
 .fdy-carousel{position:relative;}
-.fdy-carousel__viewport{display:flex;overflow-x:auto;scroll-snap-type:x mandatory;scroll-behavior:smooth;border-radius:var(--radius-lg);scrollbar-width:none;-ms-overflow-style:none;}
+/* position:relative — the arrows are positioned against .fdy-carousel (the parent), so this only
+   catches out-of-flow content inside the SLIDES, which would otherwise escape the viewport
+   entirely and scroll the page by one slide-offset per slide (see base.css). */
+.fdy-carousel__viewport{position:relative;display:flex;overflow-x:auto;scroll-snap-type:x mandatory;scroll-behavior:smooth;border-radius:var(--radius-lg);scrollbar-width:none;-ms-overflow-style:none;}
 .fdy-carousel__viewport::-webkit-scrollbar{display:none;}
 .fdy-carousel__slide{flex:0 0 100%;min-width:0;scroll-snap-align:center;}
 .fdy-carousel__arrow{position:absolute;top:50%;transform:translateY(-50%);z-index:2;display:inline-flex;align-items:center;justify-content:center;width:2.25rem;height:2.25rem;border:0;border-radius:var(--radius-full);background:color-mix(in srgb,var(--color-surface) 86%,transparent);color:var(--color-text);box-shadow:var(--shadow-2);cursor:pointer;transition:background var(--dur-fast) var(--ease-standard);}
@@ -827,6 +855,43 @@ fieldset.fdy-field>legend{padding:0;float:none;}
 /* Freeday — Keyboard key */
 .fdy-kbd{display:inline-flex;align-items:center;justify-content:center;min-width:1.5rem;height:1.5rem;padding:0 var(--space-2);font-family:var(--font-mono);font-size:var(--text-xs);color:var(--color-text);background:var(--color-surface-2);border:var(--bw) solid var(--color-border-strong);border-bottom-width:2px;border-radius:var(--radius-sm);}
 
+/* Freeday — List: the FLAT row container.
+ *
+ * USAGE.md §3 puts list rows among the surfaces that should be flat, but until now the only
+ * container the kit shipped was .fdy-card — which carries --shadow-lift (a real 34px lift). A
+ * responsive table that becomes a list below `md` therefore had to choose between a stack of
+ * shadowed cards (against the doctrine) or a hand-built box, which needs a colour and so escapes
+ * the token system. This is that missing container: one flat surface, hairline dividers, no shadow.
+ *
+ * Not to be confused with .fdy-list-reset (base.css), which only strips UA bullets/indent.
+ * Works on <ul>/<ol> (list-style is reset here) or on plain <div>s. */
+/* position:relative — containing block for out-of-flow row content (see base.css). */
+.fdy-list{position:relative;list-style:none;margin:0;padding:0;background:var(--color-surface);border:var(--bw) solid var(--color-border);border-radius:var(--radius-lg);overflow:hidden;}
+.fdy-list__row{display:flex;align-items:center;gap:var(--space-3);padding:var(--space-4) var(--space-5);min-width:0;}
+/* Divider between rows. Two shapes are supported and both are load-bearing: rows as direct children
+ * of the list, and rows wrapped in <li> (the semantic shape, where the ADJACENT siblings are the
+ * <li>s — a bare `.fdy-list__row + .fdy-list__row` silently matches nothing there). */
+.fdy-list__row + .fdy-list__row,
+.fdy-list > * + * > .fdy-list__row{border-top:var(--bw) solid var(--color-border-muted);}
+/* A row that is itself the control: render it as <button>/<a> and the UA box is reset without
+ * touching the list surface (same contract as .fdy-card--button). */
+.fdy-list__row--button{width:100%;text-align:inherit;color:inherit;font:inherit;background:none;border:0;appearance:none;-webkit-appearance:none;cursor:pointer;}
+.fdy-list__row--button:hover,.fdy-list__row--interactive:hover{background:var(--color-surface-2);}
+.fdy-list__row--button:focus-visible{outline:none;box-shadow:inset 0 0 0 2px var(--color-primary);}
+.fdy-list__row--interactive{cursor:pointer;}
+/* Disabled row. The reset above adopts the UA button box, but not its disabled state — so a row
+   disabled mid-flight (a redirect in progress, say) kept lighting up and kept a pointer cursor:
+   a control answering the pointer while refusing input. Same contract as every other disabled
+   control in the kit (dim + not-allowed), hover withdrawn, both the native and the aria- form. */
+.fdy-list__row--button:disabled,.fdy-list__row--button[aria-disabled="true"],.fdy-list__row--interactive[aria-disabled="true"]{opacity:.5;cursor:not-allowed;}
+.fdy-list__row--button:disabled:hover,.fdy-list__row--button[aria-disabled="true"]:hover,.fdy-list__row--interactive[aria-disabled="true"]:hover{background:none;}
+/* Row internals: a title/meta stack that truncates, and a trailing slot pinned right. */
+.fdy-list__main{display:flex;flex-direction:column;gap:var(--space-1);min-width:0;flex:1;}
+.fdy-list__title{font-weight:var(--weight-medium);color:var(--color-text);overflow:hidden;text-overflow:ellipsis;white-space:nowrap;}
+.fdy-list__meta{font-size:var(--text-sm);color:var(--color-text-muted);display:flex;align-items:center;gap:var(--space-2);flex-wrap:wrap;}
+.fdy-list__aside{flex:none;display:flex;align-items:center;gap:var(--space-2);}
+/* Density: rows tighten with the rest of the kit (--space-* mid-range steps under compact). */
+
 /* Freeday — Menu (action popup) + Split button. Enhanced by freeday-menu.js. */
 .fdy-menu-wrap{position:relative;display:inline-flex;}
 .fdy-menu{position:absolute;top:calc(100% + var(--space-1));left:0;z-index:130;min-width:11rem;margin:0;padding:var(--space-1);list-style:none;background:var(--color-surface);color:var(--color-text);border:var(--bw) solid var(--color-border-strong);border-radius:var(--radius-md);box-shadow:var(--shadow-3);}
@@ -1004,7 +1069,10 @@ fieldset.fdy-field>legend{padding:0;float:none;}
 .fdy-step-nav{display:flex;justify-content:space-between;gap:var(--space-2);margin-top:var(--space-5);}
 
 /* Freeday — Table */
-.fdy-table-wrap{overflow-x:auto;border:var(--bw) solid var(--color-border);border-radius:var(--radius-lg);box-shadow:var(--shadow-1);background:var(--color-surface);}
+/* position:relative on every scroller/clipper — it makes the box the containing block for its own
+   absolutely positioned content (.fdy-visually-hidden above all), which `overflow` alone does NOT
+   clip. Without it a hidden label in a wide table scrolls the whole page. See base.css. */
+.fdy-table-wrap{position:relative;overflow-x:auto;border:var(--bw) solid var(--color-border);border-radius:var(--radius-lg);box-shadow:var(--shadow-1);background:var(--color-surface);}
 .fdy-table{width:100%;border-collapse:collapse;font-size:var(--text-sm);}
 .fdy-table caption{text-align:left;padding:var(--space-3) var(--space-4);font-weight:var(--weight-semibold);color:var(--color-text);}
 .fdy-table th{text-align:left;padding:var(--space-3) var(--space-4);font-size:var(--text-xs);font-weight:var(--weight-semibold);text-transform:uppercase;letter-spacing:var(--tracking-wide);color:var(--color-text-muted);background:var(--color-surface-2);border-bottom:var(--bw) solid var(--color-border);white-space:nowrap;}
@@ -1041,7 +1109,7 @@ fieldset.fdy-field>legend{padding:0;float:none;}
 
 /* Data-table shell (toolbar + scroll + footer stay put while the table scrolls) */
 .fdy-datatable{border:var(--bw) solid var(--color-border);border-radius:var(--radius-lg);box-shadow:var(--shadow-1);background:var(--color-surface);overflow:hidden;}
-.fdy-table-scroll{overflow-x:auto;}
+.fdy-table-scroll{position:relative;overflow-x:auto;}
 .fdy-table-toolbar{display:flex;align-items:center;gap:var(--space-3);flex-wrap:wrap;padding:var(--space-3) var(--space-4);border-bottom:var(--bw) solid var(--color-border);}
 .fdy-table-toolbar__search{max-width:18rem;}
 .fdy-table-toolbar__spacer{flex:1;}
@@ -1074,7 +1142,8 @@ fieldset.fdy-field>legend{padding:0;float:none;}
 .fdy-table-bulkbar__actions{display:flex;gap:var(--space-2);}
 
 /* Freeday — Tabs (WAI-ARIA APG) */
-.fdy-tabs__list{display:flex;gap:var(--space-1);border-bottom:var(--bw) solid var(--color-border);overflow-x:auto;}
+/* position:relative — containing block for out-of-flow content in the tabs (see base.css). */
+.fdy-tabs__list{position:relative;display:flex;gap:var(--space-1);border-bottom:var(--bw) solid var(--color-border);overflow-x:auto;}
 .fdy-tabs__tab{appearance:none;border:0;background:transparent;cursor:pointer;white-space:nowrap;font-family:var(--font-body);font-size:var(--text-sm);font-weight:var(--weight-medium);color:var(--color-text-muted);padding:var(--space-3) var(--space-4);border-bottom:2px solid transparent;margin-bottom:-1px;transition:color var(--dur-fast) var(--ease-standard),border-color var(--dur-fast) var(--ease-standard);}
 .fdy-tabs__tab:hover{color:var(--color-text);}
 .fdy-tabs__tab:disabled,.fdy-tabs__tab[aria-disabled="true"]{opacity:.5;cursor:not-allowed;color:var(--color-text-muted);}

package/dist/freeday.tokens.css

@@ -176,6 +176,9 @@
   --focus-ring: var(--azure-600);
   --focus-ring-width: 2px;
 }
+/* The SYSTEM default stays root-scoped: it is a statement about the document, and dropping :root
+ * here would match every element that is not itself [data-theme="light"] — which would re-darken
+ * the children of a light panel, since they carry no attribute of their own. */
 @media (prefers-color-scheme: dark) {
   :root:not([data-theme="light"]) {
   --shadow-1: 0 1px 2px rgba(0,0,0,.4);
@@ -234,7 +237,13 @@
   --focus-ring: var(--azure-400);
   }
 }
-:root[data-theme="dark"] {
+/* The two EXPLICIT opt-ins are deliberately NOT scoped to :root, for the same reason as density
+ * below: these are inheriting custom properties, so data-theme on any ancestor re-themes just that
+ * subtree — a dark brand panel beside a light form is an ordinary layout, and it should not require
+ * re-colouring each component by hand. The root still matches, so data-theme on <html> is unchanged.
+ * Both keep the same specificity (0,1,0) as :root and come after it, so they still win there; and
+ * --light after --dark means a light island inside a dark region wins in turn. */
+[data-theme="dark"] {
   --shadow-1: 0 1px 2px rgba(0,0,0,.4);
   --shadow-2: 0 2px 6px rgba(0,0,0,.45);
   --shadow-3: 0 6px 20px -2px rgba(0,0,0,.6),0 1px 3px rgba(0,0,0,.5);
@@ -290,7 +299,7 @@
   --chart-tick: var(--slate-600);
   --focus-ring: var(--azure-400);
 }
-:root[data-theme="light"] {
+[data-theme="light"] {
   --shadow-1: 0 1px 2px rgba(16,14,30,.06);
   --shadow-2: 0 2px 6px rgba(16,14,30,.07),0 1px 2px rgba(16,14,30,.05);
   --shadow-3: 0 4px 16px -2px rgba(16,14,30,.14),0 1px 3px rgba(16,14,30,.10);
@@ -346,7 +355,11 @@
   --chart-tick: var(--slate-400);
   --focus-ring: var(--azure-600);
 }
-:root[data-density="compact"] {
+/* Density is deliberately NOT scoped to :root. These are custom properties, so they inherit —
+ * putting the attribute on any ancestor (a route wrapper, one section) densifies just that
+ * subtree, which is how density is actually decided: per screen, not per app. The root still
+ * matches, so setting data-density on the html element keeps working exactly as before. */
+[data-density="compact"] {
   --space-3: 0.625rem;
   --space-4: 0.75rem;
   --space-5: 1rem;

package/docs/agent-onboarding.md

@@ -0,0 +1,153 @@
+# Freeday — AI agent onboarding
+
+For **a coding agent working in a project that consumes Freeday** (Claude Code, Codex, Cursor,
+Copilot…). No model has Freeday in its training data, so an agent that is merely told "use Freeday"
+will invent class names or silently fall back to Bootstrap/Tailwind conventions. This file is the
+fix: paste the block below into the consuming project's agent instruction file, once.
+
+> Working on **the kit itself**, not a consuming app? That's [`../CLAUDE.md`](../CLAUDE.md) — this
+> file is about *using* the published package.
+
+---
+
+## 1. Paste this into your project's agent instructions
+
+Into `CLAUDE.md` (Claude Code) / `AGENTS.md` (Codex, others) / `.github/copilot-instructions.md` at
+the **root of the consuming project**:
+
+```markdown
+## UI: Freeday design system (@cahyo-dimas/freeday)
+
+All UI in this project is built from Freeday. It is a **token-driven CSS kit + zero-dependency JS
+enhancers**, not a component framework — components are plain markup with `fdy-*` classes.
+
+**Before writing or editing any markup/CSS, read these (they ship inside the package):**
+- `node_modules/@cahyo-dimas/freeday/COMPONENTS.md` — every class that exists, with minimal markup
+  skeletons, enhancer hooks and the a11y contract per component. **The class list is closed:
+  if a class is not in that file, it does not exist — do not invent one.**
+- `node_modules/@cahyo-dimas/freeday/USAGE.md` — the doctrine: which token/role/shadow to use when.
+- `node_modules/@cahyo-dimas/freeday/docs/reference-screen.html` — one complete screen, assembled
+  the intended way. Copy this structure for a new screen.
+
+**Non-negotiables:**
+1. No raw hex or px in app CSS. Use tokens: `var(--color-primary)`, `var(--space-4)` (4px scale),
+   `var(--radius-md)`, `var(--shadow-1)`, `var(--dur-2)`.
+2. Components only touch semantic tokens (`--color-*`) — never the primitive ramp (`--azure-600`).
+3. `.fdy-btn` is already the primary action (there is no `--primary`). One per screen; everything
+   else is `--ghost` or `--text`.
+4. Three title roles only: `.fdy-title-page` (one `<h1>`) / `.fdy-title-section` / `.fdy-title-card`.
+   Never reuse a card title as a page title.
+5. Assemble from the frame down: `.fdy-app` → `.fdy-page` → `.fdy-page-section` → components.
+6. Form errors: `aria-invalid="true"` + `aria-describedby` → a `.fdy-help.fdy-help--error`.
+   Icon-only buttons need `aria-label`. Status is never colour-only.
+7. Interactive components need their enhancer script loaded (see the table in COMPONENTS.md);
+   in an SPA, re-hydrate dynamic DOM (`useFreeday` in Vue/React does this).
+8. Freeday owns components + tokens, **not layout**. Grids/stacks/one-off gaps come from our own
+   layout layer — build its theme on `var(--space-N)` so both systems stay in step.
+```
+
+Adjust the paths if the package lives somewhere else (a workspace, a vendored copy, `wwwroot/` for
+Blazor). Then verify the agent can actually read those files — an agent that can't open
+`node_modules` will keep guessing.
+
+## 2. What ships in the package
+
+| File | What it answers |
+|---|---|
+| `COMPONENTS.md` | The complete class surface — what exists, its modifiers, minimal markup, a11y. |
+| `USAGE.md` | The doctrine — which token/role/shadow/emphasis to use when. |
+| `docs/getting-started.md` | Install + import + theme, per stack (Static HTML · Vue · React · Blazor). |
+| `docs/integrations.md` | How to bridge third-party libraries (validation, charts, dates, i18n…). |
+| `docs/reference-screen.html` | A full screen assembled from the shell down. Open it in a browser. |
+| `docs/agent-onboarding.md` | This file. |
+| `dist/` | Built CSS + enhancers. **`freeday.bundle.css` = tokens + components** (what `@cahyo-dimas/freeday/css` resolves to); `freeday.css` is components **only**, `freeday.tokens.css` tokens only — linking `freeday.css` alone leaves every `var(--…)` unresolved. Plus `freeday-*.js` and the `.d.ts` files. |
+| `src/components/*.css` | The authoritative source for every class, when a doc is ambiguous. |
+| `tokens/tokens.json` | Every token in W3C DTCG format — machine-readable. |
+| `adapters/vue` · `adapters/react` · `adapters/blazor` | Typed wrappers, 10 components each. |
+
+The live docs (with an interactive playground) are at
+<https://cahyo-dimas.github.io/freeday-ui-kit/>, and the repo — including three complete example
+apps under `examples/` (Vue, React, Blazor) that are **not** in the npm tarball — is at
+<https://github.com/cahyo-dimas/freeday-ui-kit>.
+
+## 3. Starting a new screen
+
+The order matters; skipping to components is what produces flat, identical-card screens.
+
+0. **Pick the screen shape first.** Which archetype is this — dashboard, master-detail, kanban,
+   wizard, POS…? The repo's
+   [`reference/README.md`](https://github.com/cahyo-dimas/freeday-ui-kit/blob/main/reference/README.md)
+   maps 15 archetypes to the exact primitives that compose each one, and says plainly which shapes
+   the kit has **no** component for (kanban columns, calendar month grid, chat bubbles, canvas) so
+   you build the frame instead of inventing a class. Not in the npm package — read it on GitHub.
+1. **Shell** — is `.fdy-app` already in place (usually once, in the app layout)? If not, copy it
+   from `docs/getting-started.md` §The app shell.
+2. **Theme** — `data-theme="light|dark"` + `data-density="comfortable|compact"`, normally on
+   `<html>`, set once at the root. Use `compact` for table-heavy back-office screens. Both attributes
+   also work on **any ancestor**: `<section data-theme="dark">` inverts that region and every
+   component inside it follows, so never hand-colour an inverted panel.
+3. **Fonts** — the package ships **no** `@font-face`. Load Sora / IBM Plex Sans / JetBrains Mono
+   yourself, or override `--font-display`/`--font-body`/`--font-mono`. Skipping this reads as
+   "unfinished design", not "missing dependency".
+4. **Page frame** — `.fdy-page` + `.fdy-page__header` (eyebrow + `.fdy-title-page` + desc on the
+   left, **one** primary action on the right).
+5. **Sections** — one `.fdy-page-section` per region, each with a `.fdy-title-section`.
+6. **Components** — from `COMPONENTS.md`, inside the sections.
+7. **Verify** — the checklist in §5.
+
+## 4. Migrating an existing UI to Freeday
+
+Migration is a **class-and-structure swap**, not a rewrite. Keep the app's DOM semantics; replace
+the styling layer. Rough equivalents — always confirm the target class in `COMPONENTS.md`, and note
+that Freeday deliberately has **no** layout/spacing utilities, so grid/flex/margin classes stay with
+your own layout layer:
+
+| Coming from | Freeday |
+|---|---|
+| `btn btn-primary` / `MudButton Variant=Filled` | `fdy-btn` |
+| `btn btn-secondary` / `btn-outline-*` | `fdy-btn fdy-btn--ghost` |
+| `btn btn-danger` | `fdy-btn fdy-btn--danger` |
+| `btn btn-link` | `fdy-btn fdy-btn--text` |
+| `btn-sm` / `btn-lg` | `fdy-btn--sm` / `fdy-btn--lg` |
+| `form-control` / `MudTextField` | `fdy-field` + `fdy-label` + `fdy-input` |
+| `form-select` / `<select>` / `MudSelect` | `fdy-combo` + `data-fdy-combo` (+ `freeday-select.js`) |
+| `invalid-feedback` / `is-invalid` | `aria-invalid="true"` + `fdy-help fdy-help--error` |
+| `input-group` / `input-group-text` | `fdy-input-group` + `__addon` / `__btn` |
+| `form-check` / `form-switch` | `fdy-check` / `fdy-radio` / `fdy-switch` |
+| `card` / `card-body` / `card-title` | `fdy-card` / `__body` / `__title` |
+| `table table-striped` / `MudTable` | `fdy-table` in `fdy-table-wrap`; interactive → `fdy-datatable` |
+| `badge bg-success` / `MudChip` (status) | `fdy-badge fdy-badge--success` |
+| `alert alert-danger` | `fdy-alert fdy-alert--danger` + `role="alert"` |
+| `modal` / `MudDialog` | `<dialog class="fdy-modal">` (native — drop the JS backdrop plumbing) |
+| `offcanvas` / `MudDrawer` | `<dialog class="fdy-drawer">` + `data-fdy-drawer` |
+| `nav nav-tabs` | `fdy-tabs` + `data-fdy-tabs` |
+| `breadcrumb` / `pagination` | `fdy-breadcrumb` / `fdy-pagination` (same `<nav><ol>` structure) |
+| `spinner-border` / `progress` | `fdy-spinner` / `fdy-progress` + `__bar` |
+| `toast` container + JS | `Freeday.toast({…})` — imperative, no markup to author |
+| `text-muted` | `fdy-text-muted` |
+| `d-none` / `visually-hidden` | `fdy-hidden` / `fdy-visually-hidden` |
+| `container` / `row` / `col-*` / `mb-3` / `gap-2` | **stays yours** — Freeday ships no layout utilities |
+
+Order of work that avoids a half-migrated mess:
+
+1. Load Freeday's CSS and **turn off the old framework's reset/preflight** — `base.css` is the
+   reset now. Two resets fighting is the usual source of "everything looks slightly off".
+2. Shell + theme attributes first, so tokens resolve everywhere.
+3. Then screen by screen: page frame → sections → controls. Convert a whole screen at a time;
+   half-converted screens can't be reviewed visually.
+4. Delete the old framework's CSS only when no screen references it, then grep for leftover class
+   prefixes.
+5. Replace hand-rolled modal/drawer/dropdown JS with the native-`<dialog>` components and the
+   enhancers — that is usually where the most code disappears.
+
+## 5. Verification checklist (before claiming a screen is done)
+
+- Every `fdy-*` class used appears in `COMPONENTS.md`. Grep the diff for `fdy-` and check.
+- No raw hex/rgb/px in the diff's CSS. Grep for `#` and `px`.
+- Exactly one `.fdy-btn` without a variant modifier on the screen; one `.fdy-title-page`.
+- Toggle `data-theme="dark"` on `<html>` — nothing becomes unreadable, no hard-coded white/black.
+- Toggle `data-density="compact"` — the layout still holds.
+- Keyboard: Tab reaches every control, focus is always visible, Esc closes overlays.
+- Form errors carry `aria-invalid` + a linked message; icon-only buttons have `aria-label`.
+- The interactive components on the screen have their enhancer loaded, and SPA-rendered DOM is
+  re-hydrated.