@qball-inc/tokens 0.1.0 → 1.0.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Ashay Kubal
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/colors_and_type.css

@@ -58,6 +58,10 @@
      behind a dialog). Theme-independent dark veil, matching the preview cards;
      consumed by the .scrim class and the Scrim overlay component. */
   --color-scrim:     rgba(20, 20, 20, 0.45);
+  /* Light foreground for glyphs sitting ON the dark scrim (e.g. the MediaSlot
+     embed-facade play button). Theme-independent — the scrim is always a dark
+     veil, so the glyph on it is always light. */
+  --color-on-scrim:  rgba(255, 255, 255, 0.96);
 
   /* ===== Finance / data palette (traditional hues, warm-tuned) =====
      Recognizable green/red/gold/blue for data semantics ONLY (gains,
@@ -163,6 +167,8 @@
     --data-down-bg:  rgba(226, 112, 95, 0.15);
     --data-warn-bg:  rgba(217, 180, 60, 0.16);
     --data-info-bg:  rgba(91, 155, 214, 0.15);
+    --anno-source:    #93A7B5;
+    --anno-source-bg: rgba(147, 167, 181, 0.16);
   }
 }
 

package/components.css

@@ -263,9 +263,71 @@
   transition: background var(--dur-base) var(--ease-out), color var(--dur-base) var(--ease-out);
 }
 .segmented button:last-child { border-right: 0; }
-.segmented button:hover { color: var(--text-secondary); }
+.segmented button:hover:not(:disabled) { color: var(--text-secondary); }
 .segmented button[aria-pressed="true"] { background: var(--signal-bg); color: var(--color-signal); }
 
+/* ----- Tabs ----------------------------------------------------
+   Page-level section switcher. Distinct from .segmented (a compact,
+   boxed inline toggle): Tabs are an UNDERLINE list for larger content
+   regions. Active = sage label + sage underline sitting on the list's
+   hairline baseline; inactive = muted; hover lifts to secondary. Active
+   weight is held constant (no bold) so switching tabs causes no layout
+   shift. Styled on aria-selected (which the React Tabs wrapper sets),
+   matching the .segmented aria-pressed / .menu__item aria-selected cue. */
+.tabs { font-family: var(--font-ui); }
+
+.tab-list {
+  display: flex;
+  gap: var(--space-lg);
+  border-bottom: 1px solid var(--border-default);
+}
+
+.tab {
+  appearance: none; -webkit-appearance: none;
+  margin: 0 0 -1px;                 /* overlap the list rule so the active underline replaces it */
+  padding: var(--space-sm) 0;
+  background: transparent;
+  border: 0; border-bottom: 2px solid transparent;
+  font-family: inherit; font-size: var(--size-button);
+  color: var(--text-muted);
+  cursor: pointer;
+  transition: color var(--dur-base) var(--ease-out),
+              border-color var(--dur-base) var(--ease-out);
+}
+.tab:hover:not(:disabled) { color: var(--text-secondary); }
+.tab[aria-selected="true"] {
+  color: var(--color-signal);
+  border-bottom-color: var(--color-signal);
+}
+.tab:disabled, .tab[data-disabled] { opacity: 0.4; cursor: not-allowed; }
+
+.tab-panel { padding-top: var(--space-md); color: var(--text-secondary); }
+
+/* ----- Shared focus ring ---------------------------------------
+   The library's single sage keyboard-focus ring (:focus-visible only,
+   so pointer clicks stay clean). Retrofits every interactive surface
+   that previously relied on the UA outline. One treatment, two offset
+   contexts: OUTSET for standalone controls; INSET where a container
+   would clip the ring (.segmented is overflow:hidden; the .menu /
+   .dropdown / .notif panels scroll). Additive — leaves the existing
+   border-color :focus on .input / .select / .switch untouched. */
+.btn:focus-visible,
+.iconbtn:focus-visible,
+.tab:focus-visible,
+.gwrap:focus-visible,
+.appnav a:focus-visible,
+.link:focus-visible {
+  outline: 2px solid var(--color-signal);
+  outline-offset: 2px;
+}
+.segmented button:focus-visible,
+.menu__item:focus-visible,
+.dropdown__row:focus-visible,
+.notif__item:focus-visible {
+  outline: 2px solid var(--color-signal);
+  outline-offset: -2px;
+}
+
 /* ----- Scrim / overlay backdrop --------------------------------
    The dim veil behind a modal/dialog — the brand's no-shadow lift
    partner. Full-viewport fixed layer; no blur (the preview oracle
@@ -400,6 +462,23 @@
   .skel { animation: none; background: var(--bg-surface); }
 }
 
+/* ----- AI sparkle shimmer — the icon system's ONLY animated icon ----
+   Signals ACTIVE AI. Apply the `ic-ai-shimmer` class to <AiSparkle> (it
+   merges after the base `ic`): a gentle opacity/scale twinkle paced by
+   the --duration-slow token. Reduced-motion collapses it to one static
+   sparkle (no loop) — the binding DESIGN.md Motion contract (§7a). */
+.ic-ai-shimmer {
+  transform-origin: center;
+  animation: ic-ai-shimmer calc(var(--dur-slow) * 4) ease-in-out infinite;
+}
+@keyframes ic-ai-shimmer {
+  0%, 100% { opacity: 1; transform: scale(1); }
+  50% { opacity: 0.55; transform: scale(0.92); }
+}
+@media (prefers-reduced-motion: reduce) {
+  .ic-ai-shimmer { animation: none; opacity: 1; }
+}
+
 /* ----- Empty / error / status states ---------------------------
    Centered figure: icon chip, headline, supporting line, action.
    --error reserves the red for genuine failures; --empty stays
@@ -446,6 +525,22 @@
 .gtip--cited .gtip__k { color: var(--anno-source); }
 .gtip--unverified .gtip__k { color: var(--color-highlight); }
 
+/* Portal variant of .gtip for the React <GroundingFlag> (Radix). Same reason as
+   .tip-pop: the React tooltip portals its content to <body> to escape transformed
+   ancestors (the .dock / a Modal), and a node at <body> cannot be positioned by
+   the parent-anchored .gtip rules — Radix's popper owns placement and mounts the
+   content only while open (no opacity/pointer-events gate). So this class carries
+   the SAME light guardrail-bubble visual as the .gtip oracle (light surface, 1px
+   border) MINUS positioning. The .gtip__k / .gtip__src / .gtip--cited|--unverified
+   descendants compose in unchanged. No caret — the .gtip oracle has none. */
+.gtip-pop {
+  width: max-content; max-width: 232px; text-align: left;
+  background: var(--bg-primary); border: 1px solid var(--border-strong);
+  border-radius: var(--radius-sm); padding: 9px 11px;
+  font-family: var(--font-ui); font-size: 11px; line-height: 1.5; color: var(--text-secondary);
+  z-index: 30;
+}
+
 /* canonical inline chips */
 .ground {
   display: inline-flex; align-items: center; gap: 3px;
@@ -539,11 +634,13 @@
 /* avatar (image or initials) */
 .avatar {
   width: 28px; height: 28px; flex: none; border-radius: var(--radius-sm);
-  display: grid; place-items: center; overflow: hidden;
+  display: grid; place-items: center; overflow: visible;
   background: var(--signal-bg); color: var(--color-signal);
   font-family: var(--font-display); font-size: 11px; font-weight: 700;
 }
-.avatar img { width: 100%; height: 100%; object-fit: cover; }
+/* overflow stays visible so the .avatar__status corner dot's halo isn't clipped;
+   the image self-clips to the avatar's border-radius via inherit (incl. --round 50%). */
+.avatar img { width: 100%; height: 100%; object-fit: cover; border-radius: inherit; }
 .avatar--lg { width: 38px; height: 38px; font-size: 14px; }
 .avatar--round { border-radius: 50%; }
 
@@ -824,6 +921,259 @@ html[data-theme="dark"] .theme-toggle .ic-moon { display: inline; }
 .digest--read .digest__dot { display: none; }
 .digest__skel { display: flex; flex-direction: column; gap: 9px; }
 
+/* ----- AI conversation terminal --------------------
+   The Stocky terminal transcript surface + its inline composer.
+   Ported from the conversation-terminal oracle; the generic helpers
+   (turn / prefixes / cursor / number / bullet) are BEM-namespaced
+   under .term__* so the published bundle never ships a bare global
+   .cursor / .n / .turn. The persistent AI disclaimer is the shipped
+   <Callout> (owner decision S86), NOT a terminal-local style.
+   Monospace display face; lift via border weight, no shadow. */
+.term {
+  display: flex;
+  flex-direction: column;
+  max-width: 560px;
+  font-family: var(--font-display);
+  background: var(--bg-primary);
+  border: 1px solid var(--border-strong);
+  border-radius: var(--radius-lg);
+  overflow: hidden;
+}
+.term__head {
+  padding: 11px 14px;
+  border-bottom: 0.5px solid var(--border-default);
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  font-family: var(--font-ui);
+}
+.term__caret { font-family: var(--font-display); color: var(--color-signal); font-weight: 700; font-size: 13px; }
+.term__title { font-size: 11.5px; color: var(--text-muted); letter-spacing: 0.5px; }
+.term__body {
+  padding: 4px 14px;
+  display: flex;
+  flex-direction: column;
+  font-size: 12.5px;
+  line-height: 1.65;
+  overflow-y: auto;
+}
+.term__sep { height: 0; border: 0; border-top: 0.5px solid var(--border-default); margin: 0; }
+.term__turn {
+  display: grid;
+  grid-template-columns: 56px 1fr;
+  gap: 8px;
+  align-items: start;
+  padding: 11px 0;
+}
+.term__pre--you { color: var(--color-signal); font-weight: 600; white-space: nowrap; }
+.term__pre--bot { color: var(--color-highlight); font-weight: 700; white-space: nowrap; }
+.term__txt--you { color: var(--text-primary); }
+.term__txt--bot { color: var(--text-secondary); }
+.term__num { color: var(--data-up); font-weight: 600; }
+.term__bul { color: var(--text-muted); }
+.term__cursor {
+  display: inline-block;
+  width: 7px;
+  height: 14px;
+  background: var(--color-signal);
+  vertical-align: text-bottom;
+  margin-left: 2px;
+  animation: term-blink 1s steps(1) infinite;
+}
+.term__composer {
+  padding: 11px 14px 4px;
+  border-top: 0.5px solid var(--border-default);
+  display: grid;
+  grid-template-columns: 56px 1fr auto;
+  gap: 8px;
+  align-items: start;
+}
+.term__prompt { color: var(--color-signal); font-weight: 600; white-space: nowrap; line-height: 1.65; padding-top: 9px; }
+.term__input {
+  font-family: var(--font-display);
+  font-size: 12.5px;
+  line-height: 1.65;
+  border: 0;
+  border-bottom: 1px solid var(--border-strong);
+  padding: 9px 4px;
+  min-height: 22px;
+  background: transparent;
+  color: var(--text-primary);
+  outline: none;
+  width: 100%;
+  resize: none;
+  overflow: hidden;
+  box-sizing: border-box;
+}
+.term__input:focus { border-bottom-color: var(--color-signal); }
+.term__input:disabled { opacity: 0.5; cursor: not-allowed; }
+.term__send { align-self: center; }
+.term__send:disabled { opacity: 0.4; cursor: not-allowed; }
+.term__keyhint {
+  grid-column: 2 / -1;
+  font-family: var(--font-ui);
+  font-size: 10.5px;
+  color: var(--text-muted);
+  padding: 2px 4px 4px;
+}
+/* The persistent disclaimer is the shipped <Callout> (owner S86); this is a
+   layout-only modifier that insets the bordered note inside the terminal footer
+   so it does not double-border against the .term edge. */
+.term__disc { margin: 6px 14px 12px; }
+/* An error row (also a <Callout>) surfaced inline in the transcript body. */
+.term__errrow { margin: 8px 0 2px; }
+@keyframes term-blink { 0%, 50% { opacity: 1; } 51%, 100% { opacity: 0; } }
+@media (prefers-reduced-motion: reduce) {
+  .term__cursor { animation: none; }
+}
+
+/* ----- Tool-use / skill indicator (.tuf) -------------------
+   The lifecycle chip for a skill/tool call inside the AI terminal transcript,
+   built from the signed-off design + preview/tool-use-indicator.html.
+   A transient, status-bearing chip: it reports state, it is not a control.
+   `data-state` drives the per-state color + tint, and the color flows to the
+   leading glyph + verb via currentColor. The glyph is the primary NON-color cue
+   (FR4); `partial` (caution gold) ALWAYS pairs its color with the glyph + the
+   literal word. Sage leads (running); amber stays reserved for grounding. No
+   shadow, no emoji, radius --radius-sm. The running loop reuses the shipped
+   .spinner (the one sanctioned loop) and the streaming variant reuses the
+   shipped .term__cursor — neither is re-declared here. */
+.tuf {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  padding: 3px 9px;
+  border: 1px solid var(--border-default);
+  border-radius: var(--radius-sm);
+  background: transparent;
+  font-family: var(--font-ui);
+  font-size: 11.5px;
+  line-height: 1;
+  /* §4 motion: appear = 120ms opacity fade-in; state change = 200ms color/tint
+     cross-fade. Both stop under reduced-motion below. Fades, not slides. */
+  animation: tuf-appear var(--dur-fast) var(--ease-out);
+  transition:
+    color var(--dur-base) var(--ease-out),
+    background-color var(--dur-base) var(--ease-out);
+}
+.tuf__glyph { display: inline-flex; width: 16px; height: 16px; flex: 0 0 16px; color: currentColor; }
+.tuf__glyph svg { width: 16px; height: 16px; display: block; }
+.tuf__label { color: var(--text-primary); white-space: nowrap; }
+.tuf__verb { color: currentColor; font-weight: 600; }
+.tuf__meta { font-size: 10px; color: var(--text-muted); white-space: nowrap; }
+
+/* Per-state color + tint (color drives the glyph + verb via currentColor).
+   idle/pending = neutral --bg-surface fill + hairline (pre-result states);
+   running/success/error/partial = a state-matched tint, border-free.
+   The idle rule completes the public .tuf state set for direct-CSS consumers +
+   the gallery specimen; the React ToolUseIndicator collapses idle to a null render. */
+.tuf[data-state="idle"]    { color: var(--text-muted);    background: var(--bg-surface); }
+.tuf[data-state="pending"] { color: var(--color-info);    background: var(--bg-surface); }
+.tuf[data-state="running"] { color: var(--color-signal);  background: var(--signal-bg);       border-color: transparent; }
+.tuf[data-state="success"] { color: var(--color-success); background: var(--signal-bg);       border-color: transparent; }
+.tuf[data-state="error"]   { color: var(--color-error);   background: var(--data-down-bg);    border-color: transparent; }
+.tuf[data-state="partial"] { color: var(--data-warn);     background: var(--data-warn-bg);    border-color: transparent; }
+
+@keyframes tuf-appear { from { opacity: 0; } to { opacity: 1; } }
+/* Reduced-motion: stop the appear fade + state-change cross-fade; the running
+   .spinner / .term__cursor self-stop via their own shipped rules above. NFR5. */
+@media (prefers-reduced-motion: reduce) {
+  .tuf { animation: none; transition: none; }
+}
+
+/* ----- MediaSlot — art-directed media container ---------------
+   A sized/shaped frame for heterogeneous media (image / gif / video / embed
+   facade). `aspect-ratio` reserves the box (no CLS); the inner native element
+   fills it (`overflow:hidden`). Shapes reuse the radius vocabulary + the
+   circle/pill idiom (Avatar/Badge). Container-query units (cqw) size the
+   placeholder / play affordances so they scale with the box (.dt-wrap precedent).
+   The embed facade play button sits on the shipped `--color-scrim` with a light
+   `--color-on-scrim` glyph (no shadow — scrim is the brand's lift partner).
+   The dropzone surface is the authoring visual: the CSS ships now to
+   lock the signed-off look; the upload BEHAVIOR is deferred to 4b.3a. */
+.media-slot {
+  position: relative; display: block; overflow: hidden;
+  container-type: inline-size;
+  background: var(--bg-surface); border: .5px solid var(--border-default);
+  aspect-ratio: var(--ms-aspect, 16 / 9);
+}
+.media-slot > img,
+.media-slot > video,
+.media-slot > iframe {
+  display: block; width: 100%; height: 100%; border: 0;
+  object-fit: var(--ms-fit, cover); object-position: var(--ms-pos, 50% 50%);
+}
+.media-slot--rect    { border-radius: 0; }
+.media-slot--rounded { border-radius: var(--ms-radius, var(--radius-md)); }
+.media-slot--circle  { border-radius: 50%; }
+.media-slot--pill    { border-radius: 999px; }
+
+/* empty state + passive placeholder (icon + label); scales with the box (cqw) */
+.media-slot--empty { display: grid; place-items: center; border-style: dashed; border-color: var(--border-strong); }
+.media-slot__placeholder {
+  display: flex; flex-direction: column; align-items: center; justify-content: center;
+  gap: clamp(6px, 2.2cqw, 12px); font-family: var(--font-ui);
+  font-size: clamp(11px, 5.5cqw, 15px); color: var(--text-muted);
+  text-align: center; padding: clamp(10px, 4cqw, 20px); line-height: 1.4;
+}
+.media-slot__placeholder svg { width: clamp(22px, 18cqw, 60px); height: auto; stroke: var(--text-muted); fill: none; stroke-width: 1.5; }
+/* icon-only placeholder (e.g. avatar/circle empty) — the glyph spans most of the box */
+.media-slot__placeholder--icon svg { width: clamp(30px, 48cqw, 140px); }
+
+/* drag-and-drop / upload placeholder — the AUTHORING-LAYER visual.
+   CSS ships now to lock the signed-off look; the upload behavior is deferred. */
+.media-slot--dropzone { border-style: dotted; border-color: var(--border-strong); }
+.media-slot__dropzone {
+  display: flex; flex-direction: column; align-items: center; justify-content: center;
+  gap: clamp(6px, 2.4cqw, 12px); font-family: var(--font-ui); text-align: center;
+  padding: clamp(10px, 4cqw, 20px); color: var(--text-muted);
+  font-size: clamp(10.5px, 4.6cqw, 13px); line-height: 1.4;
+}
+.media-slot__dropzone svg { width: clamp(22px, 16cqw, 48px); height: auto; stroke: var(--text-muted); fill: none; stroke-width: 1.5; }
+.media-slot__browse {
+  font-family: var(--font-ui); font-size: clamp(10px, 4cqw, 12px);
+  padding: 4px 12px; border: .5px solid var(--border-strong); border-radius: var(--radius-sm);
+  background: transparent; color: var(--text-primary); cursor: pointer;
+  transition: border-color var(--dur-fast) var(--ease-out), color var(--dur-fast) var(--ease-out);
+}
+.media-slot__browse:hover { border-color: var(--color-signal); color: var(--color-signal); }
+.media-slot__browse:focus-visible { outline: 2px solid var(--color-signal); outline-offset: 2px; }
+
+/* embed FACADE: real provider thumbnail + a real play <button> on a DARK SCRIM
+   (so it never blends into the thumbnail). Click swaps the real iframe; never
+   auto-load. */
+.media-slot__poster { position: absolute; inset: 0; width: 100%; height: 100%; object-fit: cover; }
+.media-slot__play {
+  position: absolute; inset: 0; margin: auto;
+  width: clamp(46px, 26cqw, 74px); height: clamp(46px, 26cqw, 74px);
+  display: grid; place-items: center; border: 0; border-radius: 50%;
+  background: var(--color-scrim); color: var(--color-on-scrim);
+  cursor: pointer; transition: background var(--dur-fast) var(--ease-out), color var(--dur-fast) var(--ease-out);
+}
+.media-slot__play .tri {
+  width: 0; height: 0; margin-left: 14%;
+  border-style: solid; border-width: 0.9em 0 0.9em 1.5em;
+  border-color: transparent transparent transparent currentColor;
+}
+.media-slot__play:hover { background: var(--color-signal); color: var(--color-on-scrim); }
+.media-slot__play:focus-visible { outline: 2px solid var(--color-signal); outline-offset: 3px; }
+
+/* in-frame type chip — optional; rendered only when the consumer passes `badge` */
+.media-slot__badge {
+  position: absolute; top: 7px; left: 7px;
+  font-family: var(--font-ui); font-size: 9.5px; letter-spacing: .4px;
+  text-transform: uppercase; color: var(--text-muted);
+  background: var(--bg-surface); border: .5px solid var(--border-default);
+  border-radius: var(--radius-sm); padding: 2px 6px;
+}
+
+/* Reduced-motion: gif-as-video autoplay is gated in the component (autoPlay
+   suppressed under prefers-reduced-motion); native <img> GIFs animate per the UA.
+   Cut the facade/browse hover micro-transitions too. NFR5. */
+@media (prefers-reduced-motion: reduce) {
+  .media-slot__play, .media-slot__browse { transition: none; }
+}
+
 /* ----- Scrollbar (design-system default) ------------------------
    Thin, unobtrusive, token-driven. Track is transparent; the thumb
    uses the strong border token and darkens on hover. Applies to any

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qball-inc/tokens",
-  "version": "0.1.0",
+  "version": "1.0.0",
   "description": "QBall Design System tokens — framework-agnostic CSS custom properties, component classes, and a DTCG/Style-Dictionary JSON mirror. Zero build step; public default display face is Fira Code (Berkeley Mono restored per README in private builds).",
   "keywords": [
     "design-tokens",
@@ -33,4 +33,4 @@
     "components.css",
     "tokens.json"
   ]
-}
+}

package/theme.css

@@ -47,6 +47,7 @@
   --color-signal-bg: rgba(63,107,91,0.10);
   --color-highlight-bg: rgba(180,83,9,0.10);
   --color-scrim: rgba(20,20,20,0.45);  /* modal/overlay scrim (theme-independent) */
+  --color-on-scrim: rgba(255,255,255,0.96);  /* light glyph on the dark scrim (theme-independent) */
 
   /* finance / data palette — SEMANTICS ONLY, never wayfinding */
   --color-up: #2E7D4F;  --color-down: #B5342B;  --color-warn: #9A7D0F;