rift-ds 1.5.0 → 1.6.0

package/README.md

@@ -73,13 +73,13 @@ import 'rift-ds/tokens/presets/presets.css';
 
 ## Components
 
-<!-- component-count -->147<!-- /component-count --> components, including a chat set for AI products (Chat thread, Composer, Tool call, Reasoning, Thread panel) and Shader field, a WebGL2 ambient background whose light sources read your colour tokens at runtime, so it re-themes with everything else. Details and live examples are on the [docs site](https://rift-ds.com/components).
+<!-- component-count -->149<!-- /component-count --> components, including a chat set for AI products (Chat thread, Composer, Tool call, Reasoning, Thread panel) and Shader field, a WebGL2 ambient background whose light sources read your colour tokens at runtime, so it re-themes with everything else. Details and live examples are on the [docs site](https://rift-ds.com/components).
 
 <details>
 <summary>The full list</summary>
 
 <!-- component-list:start -->
-Accordion · Agent plan · Agent rail · Agent status · AI button · Alert · Alert dialog · Anchor nav · Animated number · App layout · App sidebar · Area chart · Attachment drop zone · Attachment group · Attachment tile · Attachment viewer · Avatar · Avatar group · Badge · Banner · Bar chart · Bottom nav · Breadcrumb · Button · Button group · Card · Card stack · Carousel · Chat header · Chat marker · Chat message · Chat thread · Checkbox · Chip · Circular button · Code block · Code diff · Colour picker · Combo chart · Combobox · Command palette · Composer · Contact card · Context menu · Contribution graph · Data table · Date input · Date picker · Dialog · Divider · Document chip · Drawer · Dropdown · Dropdown menu · Empty state · Entity card · Event calendar · Field · Figure · File input · Filter bar · Funnel chart · Gantt chart · Gauge · Globe · Hover card · Image compare · Input · Inspector colour picker · Inspector dropdown · Inspector input · Inspector section · Inspector segments · Inspector slider · Inspector toggle switch · Instructions · Interrupt card · Kbd · Legend tile · Lightbox · Line chart · Link list · Map callout · Map legend · Message actions · Message card · Meter · Model picker · Nav · Nav list · Notification centre · Number input · Pagination · Panel · Pie chart · Pin input · Popover · Progress bar · Prompt suggestions · Prose · Quote · Radar chart · Radial chart · Radio button · Rating · Reasoning · Rich dropdown · Scatter chart · Section title · Segmented control · Selection card · Shader field · Sidebar panel · Skeleton · Slider · Source chip · Source trail · Sparkline · Spinner · Split button · Split pane · Stacked bar chart · Stat · Status dot · Stepper · Streaming text · Swatch · Table · Tabs · Tag input · Textarea · Thread panel · Thread tabs · Time picker · Timeline · Toast · Toggle group · Toggle switch · Tool call · Toolbar · Tooltip · Top app bar · Tree view · Treemap · Usage card · Waveform · World map
+Accordion · Agent plan · Agent rail · Agent status · AI button · Alert · Alert dialog · Anchor nav · Animated number · App layout · App sidebar · Area chart · Attachment drop zone · Attachment group · Attachment tile · Attachment viewer · Avatar · Avatar group · Badge · Banner · Bar chart · Bottom nav · Breadcrumb · Button · Button group · Card · Card stack · Carousel · Chat header · Chat marker · Chat message · Chat thread · Checkbox · Chip · Circular button · Code block · Code diff · Colour picker · Combo chart · Combobox · Command palette · Composer · Contact card · Context menu · Contribution graph · Data table · Date input · Date picker · Dialog · Divider · Document chip · Drawer · Dropdown · Dropdown menu · Empty state · Entity card · Event calendar · Field · Figure · File input · Filter bar · Funnel chart · Gantt chart · Gauge · Globe · Hover card · Image compare · Input · Inspector colour picker · Inspector dropdown · Inspector input · Inspector section · Inspector segments · Inspector slider · Inspector toggle switch · Instructions · Interrupt card · Kbd · Legend tile · Lightbox · Line chart · Link list · Map callout · Map legend · Message actions · Message card · Meter · Model picker · Nav · Nav list · Notification centre · Number input · Pagination · Panel · Pie chart · Pin input · Pixel avatar · Popover · Progress bar · Prompt suggestions · Prose · Quote · Radar chart · Radial chart · Radio button · Rating · Reasoning · Rich dropdown · Scatter chart · Section title · Segmented control · Selection card · Shader field · Sidebar panel · Skeleton · Slider · Source chip · Source trail · Sparkline · Spinner · Split button · Split pane · Stacked bar chart · Stat · Status dot · Stepper · Streaming text · Swatch · Table · Tabs · Tag input · Textarea · Thread panel · Thread tabs · Time picker · Timeline · Toast · Toggle group · Toggle switch · Tool call · Toolbar · Tooltip · Top app bar · Tree view · Treemap · Usage card · Waveform · Widget · World map
 <!-- component-list:end -->
 
 </details>

package/components/AppSidebar/AppSidebar.css

@@ -227,6 +227,12 @@
   flex-shrink: 0;
 }
 
+/* A generated avatar in the icon seat: a block-level sprite, so the seat
+   lays it out as a box rather than on the text baseline. */
+.ds-app-sidebar__btn-icon--avatar {
+  display: inline-flex;
+}
+
 .ds-app-sidebar__btn-label {
   font-family: var(--font-paragraph-emphasis-family);
   font-size: var(--font-paragraph-emphasis-size);

package/components/AppSidebar/AppSidebar.d.ts

@@ -23,8 +23,18 @@ export interface AppSidebarSubItem {
 export interface AppSidebarItem {
     /** Unique key for this item */
     key: string;
-    /** Item icon — Material Symbol name (string) or custom element (ReactNode) */
-    icon: string | React.ReactNode;
+    /** Item icon — Material Symbol name (string) or custom element (ReactNode). Optional only when `pixelAvatar` draws the mark instead */
+    icon?: string | React.ReactNode;
+    /**
+     * Draws a generated PixelAvatar in the icon seat instead of `icon`, for
+     * rows that name a thing rather than a place — projects, workspaces,
+     * accounts. `true` seeds the character from `label`; a string seeds it
+     * from that value, so a renamed item can keep its character by passing a
+     * stable id. The sidebar spreads the inks across all of its avatar rows,
+     * so neighbours differ in colour as well as shape. The character is
+     * decorative: the label beside it is the name
+     */
+    pixelAvatar?: boolean | string;
     /** Display label (shown when expanded) */
     label: string;
     /** Click handler — also fires on a link item, so a consumer can route client-side */

package/components/AppSidebar/AppSidebar.js

@@ -5,9 +5,11 @@ import { useLayer } from "../../behaviors/useLayer.js";
 import { useFocusScope } from "../../behaviors/useFocusScope.js";
 import { useScrollLock } from "../../behaviors/useScrollLock.js";
 import { Avatar } from "../Avatar/Avatar.js";
+import { PixelAvatar } from "../PixelAvatar/PixelAvatar.js";
 import { SidebarPanel } from "../SidebarPanel/SidebarPanel.js";
 import "./AppSidebar.css";
 import "../../fonts/material-symbols.css";
+import { distinctPixelInks } from "../PixelAvatar/pixelInks.js";
 function DefaultLogo() {
   return /* @__PURE__ */ jsxs(
     "svg",
@@ -49,6 +51,14 @@ const AppSidebar = ({
   showMobileTrigger = true
 }) => {
   const baseClass = "ds-app-sidebar";
+  const avatarSeed = (item) => typeof item.pixelAvatar === "string" ? item.pixelAvatar : item.label;
+  const avatarItems = sections.flatMap(
+    (section) => section.items.filter((item) => item.pixelAvatar)
+  );
+  const avatarInks = /* @__PURE__ */ new Map();
+  distinctPixelInks(avatarItems.map(avatarSeed)).forEach((ink, index) => {
+    avatarInks.set(avatarItems[index].key, ink);
+  });
   const [internalExpanded, setInternalExpanded] = useState(defaultExpanded);
   const isExpanded = controlledExpanded ?? internalExpanded;
   const onExpandedChangeRef = useRef(onExpandedChange);
@@ -281,7 +291,7 @@ const AppSidebar = ({
             ].filter(Boolean).join(" ");
             const itemContent = /* @__PURE__ */ jsxs(Fragment, { children: [
               /* @__PURE__ */ jsxs("span", { className: `${baseClass}__btn-left`, children: [
-                /* @__PURE__ */ jsx(
+                item.pixelAvatar ? /* @__PURE__ */ jsx("span", { className: `${baseClass}__btn-icon ${baseClass}__btn-icon--avatar`, children: /* @__PURE__ */ jsx(PixelAvatar, { name: avatarSeed(item), ink: avatarInks.get(item.key) }) }) : /* @__PURE__ */ jsx(
                   "span",
                   {
                     className: `${baseClass}__btn-icon${typeof item.icon === "string" ? " material-symbols-rounded" : ""}`,

package/components/PixelAvatar/PixelAvatar.css

@@ -0,0 +1,79 @@
+/* ============================================
+   PIXEL AVATAR COMPONENT
+   A generated character mark, drawn from a name
+   ============================================ */
+
+/* Base — the character rides the icon scale, so it seats wherever an icon
+   does. A host that already sets --icon-size on its icon seat is matched by
+   the size classes below, which set the same variable. */
+
+.ds-pixel-avatar {
+  display: inline-flex;
+  flex-shrink: 0;
+  box-sizing: border-box;
+  width: var(--icon-size);
+  height: var(--icon-size);
+  color: var(--ds-pixel-avatar-ink);
+}
+
+.ds-pixel-avatar__sprite {
+  display: block;
+  width: 100%;
+  height: 100%;
+  fill: currentColor;
+}
+
+/* Sizes */
+
+.ds-pixel-avatar--sm {
+  --icon-size: var(--icon-size-500);
+}
+
+.ds-pixel-avatar--md {
+  --icon-size: var(--icon-size-600);
+}
+
+.ds-pixel-avatar--lg {
+  --icon-size: var(--icon-size-800);
+}
+
+.ds-pixel-avatar--xl {
+  --icon-size: var(--icon-size-1200);
+}
+
+/* Inks — one rule per pixel ink token. The tokens carry a light and a dark
+   value each, so the character holds its contrast in both themes. */
+
+.ds-pixel-avatar--ink-1 {
+  --ds-pixel-avatar-ink: var(--color-pixel-ink-1);
+}
+
+.ds-pixel-avatar--ink-2 {
+  --ds-pixel-avatar-ink: var(--color-pixel-ink-2);
+}
+
+.ds-pixel-avatar--ink-3 {
+  --ds-pixel-avatar-ink: var(--color-pixel-ink-3);
+}
+
+.ds-pixel-avatar--ink-4 {
+  --ds-pixel-avatar-ink: var(--color-pixel-ink-4);
+}
+
+.ds-pixel-avatar--ink-5 {
+  --ds-pixel-avatar-ink: var(--color-pixel-ink-5);
+}
+
+.ds-pixel-avatar--ink-6 {
+  --ds-pixel-avatar-ink: var(--color-pixel-ink-6);
+}
+
+/* Variants — the tile is the same sprite on a wash of its own ink. The
+   padding comes from the size, not a percentage, which would resolve against
+   the host's width rather than the tile's. */
+
+.ds-pixel-avatar--tile {
+  padding: calc(var(--icon-size) / 16);
+  border-radius: var(--radius-200);
+  background-color: color-mix(in srgb, var(--ds-pixel-avatar-ink) 16%, transparent);
+}

package/components/PixelAvatar/PixelAvatar.d.ts

@@ -0,0 +1,47 @@
+import { default as React } from 'react';
+import { PixelInk } from './pixelInks';
+export { distinctPixelInks, pixelAvatarInk } from './pixelInks';
+export type { PixelInk } from './pixelInks';
+/** Props owned by PixelAvatar itself — everything else falls through to the root span. */
+type PixelAvatarOwnProps = {
+    /**
+     * The seed. The same name always draws the same character in the same
+     * ink, so a project, workspace or thread has its mark the moment it has a
+     * name, with nothing designed or stored for it.
+     */
+    name: string;
+    /** Rendered size, on the icon scale (`--icon-size-500/600/800/1200` — 20, 24, 32 and 48px), so the character seats wherever an icon does. */
+    size?: 'sm' | 'md' | 'lg' | 'xl';
+    /**
+     * Overrides the ink the name picks (1 to 6, the `--color-pixel-ink-*`
+     * tokens). A name's own ink is one of six, so two neighbours can land on
+     * the same one; a host drawing a list passes each row's entry from
+     * `distinctPixelInks` here to keep them apart. The character's shape still
+     * comes from the name.
+     */
+    ink?: PixelInk;
+    /** `plain` draws the character alone; `tile` seats it on a rounded wash of its own ink, for a larger standalone mark. */
+    variant?: 'plain' | 'tile';
+    /**
+     * Accessible name. Omit it when the mark sits beside the name it was
+     * drawn from, which is the usual case: the character is then decorative
+     * and hidden from assistive technology. Given, the root becomes an image
+     * with this label.
+     */
+    label?: string;
+    /** Additional CSS classes */
+    className?: string;
+};
+export interface PixelAvatarProps extends PixelAvatarOwnProps, Omit<React.ComponentPropsWithoutRef<'span'>, keyof PixelAvatarOwnProps> {
+}
+/**
+ * PixelAvatar — a generated character mark. The name is the seed: a small
+ * pixel creature and one of six inks are drawn from it, deterministically,
+ * so the same name is always the same character and nothing has to be
+ * designed, uploaded or stored. For the things that have a name before they
+ * have a logo — projects, workspaces, repositories, agents.
+ *
+ * Pure: no hooks, no random source and no browser API, so the server and the
+ * client draw the same sprite and it renders from a Server Component.
+ */
+export declare const PixelAvatar: React.ForwardRefExoticComponent<PixelAvatarProps & React.RefAttributes<HTMLSpanElement>>;

package/components/PixelAvatar/PixelAvatar.js

@@ -0,0 +1,90 @@
+import { jsx } from "react/jsx-runtime";
+import React from "react";
+import { hashName, pixelAvatarInk } from "./pixelInks.js";
+import { distinctPixelInks } from "./pixelInks.js";
+import "./PixelAvatar.css";
+const GRID = 8;
+const MARGIN = 1;
+const ROW_CHANCES = [
+  [0, 0.3, 0.25, 0.15],
+  // antennae
+  [0.1, 0.75, 1, 1],
+  // crown
+  [0.55, 1, 1, 1],
+  // head
+  [0.75, 1, 1, 1],
+  // eyes (one cell is carved out below)
+  [0.7, 1, 1, 1],
+  // cheeks
+  [0.35, 0.85, 0.9, 0.7],
+  // jaw
+  [0.45, 0.5, 0.45, 0.35],
+  // legs
+  [0.35, 0.3, 0.25, 0.1]
+  // feet
+];
+const EYE_ROW = 3;
+function seeded(seed) {
+  let state = seed;
+  return () => {
+    state = state + 1831565813 | 0;
+    let t = Math.imul(state ^ state >>> 15, 1 | state);
+    t = t + Math.imul(t ^ t >>> 7, 61 | t) ^ t;
+    return ((t ^ t >>> 14) >>> 0) / 4294967296;
+  };
+}
+function spriteCells(name) {
+  const next = seeded(hashName(name));
+  const eyeColumn = next() < 0.6 ? 2 : 1;
+  const cells = [];
+  ROW_CHANCES.forEach((chances, row) => {
+    chances.forEach((chance, column) => {
+      if (next() >= chance) return;
+      if (row === EYE_ROW && column === eyeColumn) return;
+      cells.push([column, row], [GRID - 1 - column, row]);
+    });
+  });
+  return cells;
+}
+const PixelAvatar = React.forwardRef(
+  ({ name, size = "md", variant = "plain", ink: inkOverride, label, className = "", ...rest }, ref) => {
+    const baseClass = "ds-pixel-avatar";
+    const ink = inkOverride ?? pixelAvatarInk(name);
+    const classes = [
+      baseClass,
+      `${baseClass}--${size}`,
+      `${baseClass}--${variant}`,
+      `${baseClass}--ink-${ink}`,
+      className
+    ].filter(Boolean).join(" ");
+    const viewBox = `${-MARGIN} ${-MARGIN} ${GRID + MARGIN * 2} ${GRID + MARGIN * 2}`;
+    return /* @__PURE__ */ jsx(
+      "span",
+      {
+        ...rest,
+        ref,
+        className: classes,
+        role: label ? "img" : void 0,
+        "aria-label": label,
+        "aria-hidden": label ? void 0 : true,
+        children: /* @__PURE__ */ jsx(
+          "svg",
+          {
+            className: `${baseClass}__sprite`,
+            viewBox,
+            shapeRendering: "crispEdges",
+            focusable: "false",
+            "aria-hidden": "true",
+            children: spriteCells(name).map(([column, row]) => /* @__PURE__ */ jsx("rect", { x: column, y: row, width: 1, height: 1 }, `${column}-${row}`))
+          }
+        )
+      }
+    );
+  }
+);
+PixelAvatar.displayName = "PixelAvatar";
+export {
+  PixelAvatar,
+  distinctPixelInks,
+  pixelAvatarInk
+};

package/components/PixelAvatar/pixelInks.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The ink side of PixelAvatar, kept apart from the component so a host that
+ * lays out a list can compute its inks without rendering anything. The
+ * component re-exports everything here; this module has no subpath of its
+ * own.
+ */
+/** One of the six pixel inks, by token number. */
+export type PixelInk = 1 | 2 | 3 | 4 | 5 | 6;
+/** FNV-1a, 32-bit: a small stable hash of a name. */
+export declare function hashName(name: string): number;
+/** The ink a name picks for itself: stable, and one of six. */
+export declare function pixelAvatarInk(name: string): PixelInk;
+/**
+ * Inks for a list of names shown together, in order, so neighbours are told
+ * apart by colour as well as by shape. Each name keeps the ink it picks for
+ * itself when that ink is still among the least used in the list so far and
+ * sits clear of the row before it; otherwise it takes the next ink round the
+ * set that does. "Clear" means at least two steps away on the hue ring the
+ * inks are numbered round (red, orange, yellow, green, blue, purple), so a
+ * row never follows its own colour or the hue beside it: a muted theme
+ * draws neighbouring hues close together, and two warm tans in a row read
+ * as the same mark. The first six names therefore all differ, and a longer
+ * list repeats as evenly as it can. Deterministic
+ * for a given list, so server and client agree; a name's ink can change when
+ * the list around it does, which is the price of the guarantee.
+ */
+export declare function distinctPixelInks(names: readonly string[]): PixelInk[];

package/components/PixelAvatar/pixelInks.js

@@ -0,0 +1,45 @@
+const INKS = 6;
+function hashName(name) {
+  let hash = 2166136261;
+  for (let i = 0; i < name.length; i += 1) {
+    hash ^= name.charCodeAt(i);
+    hash = Math.imul(hash, 16777619);
+  }
+  return hash >>> 0;
+}
+function pixelAvatarInk(name) {
+  return hashName(`${name}:colour`) % INKS + 1;
+}
+function distinctPixelInks(names) {
+  const used = new Array(INKS).fill(0);
+  const inks = [];
+  names.forEach((name) => {
+    const own = pixelAvatarInk(name) - 1;
+    const fewest = Math.min(...used);
+    const previous = inks.length > 0 ? inks[inks.length - 1] - 1 : -1;
+    let clear = -1;
+    let different = -1;
+    let any = -1;
+    for (let step = 0; step < INKS; step += 1) {
+      const candidate = (own + step) % INKS;
+      if (used[candidate] !== fewest) continue;
+      if (any === -1) any = candidate;
+      if (candidate === previous) continue;
+      if (different === -1) different = candidate;
+      const apart = Math.abs(candidate - previous);
+      if (previous === -1 || Math.min(apart, INKS - apart) >= 2) {
+        clear = candidate;
+        break;
+      }
+    }
+    const chosen = clear !== -1 ? clear : different !== -1 ? different : any;
+    used[chosen] += 1;
+    inks.push(chosen + 1);
+  });
+  return inks;
+}
+export {
+  distinctPixelInks,
+  hashName,
+  pixelAvatarInk
+};

package/components/PromptSuggestions/PromptSuggestions.css

@@ -77,6 +77,224 @@
   align-items: flex-start;
 }
 
+/* ============================================
+   TILES and CARDS — blocks for a home screen
+   Where the chip layouts are a line of prompts,
+   these are a row of places to start: an even
+   grid that folds as the row's own width narrows,
+   so a docked panel folds while a full-width page
+   does not.
+   ============================================ */
+
+/* The column floor is stated on the icon scale, the one size both blocks
+   are drawn from: a tile is never narrower than three cover icons, a card
+   than four. Four tiles or three cards sit in one row on a conversation
+   column and fold to two columns and one on a phone, with no breakpoint. */
+.ds-prompt-suggestions--tiles,
+.ds-prompt-suggestions--cards {
+  display: grid;
+}
+
+.ds-prompt-suggestions--tiles {
+  grid-template-columns: repeat(auto-fit, minmax(calc(var(--icon-size-1200) * 3), 1fr));
+}
+
+.ds-prompt-suggestions--cards {
+  grid-template-columns: repeat(auto-fit, minmax(calc(var(--icon-size-1200) * 4), 1fr));
+}
+
+.ds-prompt-suggestions--tiles .ds-prompt-suggestions__item,
+.ds-prompt-suggestions--cards .ds-prompt-suggestions__item {
+  flex-shrink: 1;
+  min-width: 0;
+}
+
+/* One surface for both blocks: a hairline round a container that lets the
+   page through, blurred so text stays on a calm field over an ambient
+   background. The navigation-tile radius, per the radius scale. */
+.ds-prompt-suggestions__tile,
+.ds-prompt-suggestions__card {
+  display: flex;
+  flex-direction: column;
+  box-sizing: border-box;
+  width: 100%;
+  min-width: 0;
+  margin: 0;
+  border: var(--border-025) solid var(--color-bg-container-border);
+  border-radius: var(--radius-600);
+  background-color: var(--color-bg-container-primary-semi);
+  -webkit-backdrop-filter: blur(24px);
+  backdrop-filter: blur(24px);
+  color: inherit;
+  font: inherit;
+  text-align: left;
+  cursor: pointer;
+}
+
+/* A tile answers the pointer quietly, in place: the fill firms up to the
+   solid container and the hairline steps up to the tertiary text ink, so
+   the block reads as picked out without moving. */
+.ds-prompt-suggestions__tile {
+  transition:
+    background-color var(--motion-duration-fast) var(--motion-ease-standard),
+    border-color var(--motion-duration-fast) var(--motion-ease-standard);
+}
+
+.ds-prompt-suggestions__tile:hover {
+  background-color: var(--color-bg-container-primary);
+  border-color: var(--color-text-tertiary);
+}
+
+/* A card lifts: the Card component's own hover, the same rise and the same
+   sanctioned shadow, so a prompt card and a navigation tile answer the
+   pointer the same way. */
+.ds-prompt-suggestions__card {
+  transition:
+    transform var(--motion-duration-slow) var(--motion-ease-standard),
+    box-shadow var(--motion-duration-slow) var(--motion-ease-standard);
+  /* ds-allow(color): transparent resting state of the sanctioned Card
+     hover-lift shadow (see design.md — Do's and Don'ts). */
+  box-shadow: 0 0 0 rgba(0, 0, 0, 0);
+}
+
+.ds-prompt-suggestions__card:hover {
+  transform: translateY(-4px);
+  /* ds-allow(color): the sanctioned Card hover-lift shadow, restated so the
+     two tiles lift alike (see design.md — Do's and Don'ts). */
+  box-shadow: 0 8px 24px rgba(0, 0, 0, 0.3);
+}
+
+/* The pending shells are not targets, so they neither lift nor light. */
+.ds-prompt-suggestions__tile--pending:hover {
+  background-color: var(--color-bg-container-primary-semi);
+  border-color: var(--color-bg-container-border);
+}
+
+.ds-prompt-suggestions__card--pending:hover {
+  transform: none;
+  box-shadow: none;
+}
+
+.ds-prompt-suggestions__tile:focus-visible,
+.ds-prompt-suggestions__card:focus-visible {
+  outline: 2px solid var(--color-action-primary-bg);
+  outline-offset: 2px;
+}
+
+.ds-prompt-suggestions__tile {
+  gap: var(--gap-300);
+  padding: var(--padding-400);
+}
+
+.ds-prompt-suggestions__card {
+  gap: var(--gap-200);
+  padding: var(--padding-200) var(--padding-200) var(--padding-400);
+}
+
+.ds-prompt-suggestions__text {
+  display: flex;
+  flex-direction: column;
+  gap: var(--gap-050);
+  min-width: 0;
+}
+
+.ds-prompt-suggestions__card .ds-prompt-suggestions__text {
+  padding-inline: var(--padding-200);
+}
+
+.ds-prompt-suggestions__label {
+  font-family: var(--font-paragraph-sm-emphasis-family);
+  font-size: var(--font-paragraph-sm-emphasis-size);
+  font-weight: var(--font-paragraph-sm-emphasis-weight);
+  line-height: var(--font-paragraph-sm-emphasis-line-height);
+  letter-spacing: var(--font-paragraph-sm-emphasis-letter-spacing);
+  color: var(--color-text-primary);
+}
+
+.ds-prompt-suggestions__description {
+  font-family: var(--font-caption-family);
+  font-size: var(--font-caption-size);
+  font-weight: var(--font-caption-weight);
+  line-height: var(--font-caption-line-height);
+  letter-spacing: var(--font-caption-letter-spacing);
+  color: var(--color-text-tertiary);
+}
+
+.ds-prompt-suggestions__icon {
+  display: inline-flex;
+  --icon-size: var(--icon-size-600);
+  color: var(--color-icon-secondary);
+}
+
+/* The card's cover: a wash of one pixel ink, strong at the top and nearly
+   gone by the floor, with the subject's icon standing in it in the same
+   ink. The inks cycle by position, so a row of cards is told apart by
+   colour as well as by title, and they are the theme-split set, so the icon
+   holds its contrast in both modes. */
+.ds-prompt-suggestions__cover {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  /* Twice the cover icon's own size: the icon scale sets the proportion. */
+  height: calc(var(--icon-size-1200) * 2);
+  border-radius: var(--radius-400);
+  background-image: linear-gradient(
+    to bottom,
+    color-mix(in srgb, var(--ds-prompt-suggestions-tint) 24%, transparent),
+    color-mix(in srgb, var(--ds-prompt-suggestions-tint) 6%, transparent)
+  );
+}
+
+.ds-prompt-suggestions__cover .ds-prompt-suggestions__icon {
+  --icon-size: var(--icon-size-1200);
+  color: var(--ds-prompt-suggestions-tint);
+}
+
+.ds-prompt-suggestions__item:nth-child(6n + 1) { --ds-prompt-suggestions-tint: var(--color-pixel-ink-4); }
+.ds-prompt-suggestions__item:nth-child(6n + 2) { --ds-prompt-suggestions-tint: var(--color-pixel-ink-1); }
+.ds-prompt-suggestions__item:nth-child(6n + 3) { --ds-prompt-suggestions-tint: var(--color-pixel-ink-2); }
+.ds-prompt-suggestions__item:nth-child(6n + 4) { --ds-prompt-suggestions-tint: var(--color-pixel-ink-5); }
+.ds-prompt-suggestions__item:nth-child(6n + 5) { --ds-prompt-suggestions-tint: var(--color-pixel-ink-6); }
+.ds-prompt-suggestions__item:nth-child(6n) { --ds-prompt-suggestions-tint: var(--color-pixel-ink-3); }
+
+/* Pending blocks: the real shell holding the label's bar, so the row keeps
+   its height when the suggestions land. */
+.ds-prompt-suggestions__tile--pending,
+.ds-prompt-suggestions__card--pending {
+  cursor: default;
+  font-size: var(--font-paragraph-sm-emphasis-size);
+}
+
+.ds-prompt-suggestions__tile--pending {
+  justify-content: flex-end;
+  min-height: calc(
+    var(--icon-size-600) + var(--gap-300) + var(--font-paragraph-sm-emphasis-line-height) +
+      var(--font-caption-line-height) + 2 * var(--padding-400)
+  );
+}
+
+/* A pending card stands as tall as the loaded one it holds room for: the
+   cover, the label line, and two lines of description (the longest a card's
+   question runs at this width), so the row does not grow when they land. */
+.ds-prompt-suggestions__card--pending {
+  min-height: calc(
+    var(--icon-size-1200) * 2 + var(--gap-200) + var(--font-paragraph-sm-emphasis-line-height) +
+      var(--gap-050) + 2 * var(--font-caption-line-height) + var(--padding-200) +
+      var(--padding-400) + 2 * var(--border-025)
+  );
+}
+
+.ds-prompt-suggestions__card--pending .ds-prompt-suggestions__skeleton-bar {
+  margin: var(--padding-150) var(--padding-200);
+  width: auto;
+}
+
+/* The chosen block takes the same press-and-spring the chips do. */
+.ds-prompt-suggestions__item--chosen .ds-prompt-suggestions__tile,
+.ds-prompt-suggestions__item--chosen .ds-prompt-suggestions__card {
+  animation: ds-prompt-suggestions-choose var(--motion-duration-slow) var(--motion-ease-spring);
+}
+
 /* ============================================
    ITEMS
    ============================================ */

package/components/PromptSuggestions/PromptSuggestions.d.ts

@@ -5,8 +5,10 @@ export interface PromptSuggestion {
     id: string;
     /** The suggestion text shown in the chip. */
     label: string;
-    /** Optional leading icon — Material Symbol name (string) or custom element (ReactNode). */
+    /** Optional leading icon — Material Symbol name (string) or custom element (ReactNode). In the `cards` layout it stands in the card's cover. */
     icon?: string | React.ReactNode;
+    /** A quiet second line under the label, drawn by the `tiles` and `cards` layouts: what the tile leads to, or the full question a card asks. The chip layouts have no room for it and leave it out. */
+    description?: string;
 }
 /** Props owned by PromptSuggestions itself — everything else falls through to the root element. */
 type PromptSuggestionsOwnProps = {
@@ -19,9 +21,14 @@ type PromptSuggestionsOwnProps = {
      * sideways behind edge fades. `wrap` runs them across as many lines as
      * they need, for empty-state hero placements. `stack` gives each one its
      * own line, for narrow columns where a wrapped row breaks unevenly and
-     * the ragged right edge reads as an accident.
+     * the ragged right edge reads as an accident. `tiles` and `cards` leave
+     * the chip behind for an empty-state home screen: `tiles` is an even row
+     * of quiet blocks, each an icon over a label and its `description`;
+     * `cards` gives each suggestion a tinted cover holding its icon, with the
+     * label and description beneath. Both fold to fewer columns as their own
+     * width narrows.
      */
-    layout?: 'scroll' | 'wrap' | 'stack';
+    layout?: 'scroll' | 'wrap' | 'stack' | 'tiles' | 'cards';
     /**
      * Legacy alias for `layout="wrap"`; ignored when `layout` is set.
      * @deprecated Use `layout` instead, which also covers `stack`.