@appinternalleads/ui 0.2.0

package/src/ds/Banner.tsx

@@ -0,0 +1,116 @@
+import type { ReactNode } from 'react';
+import type { StyleProp, ViewStyle } from 'react-native';
+import { Box, Icon, Pressable, Text } from '../core';
+import type { IconName, InkToken } from '../core';
+import { useDs } from '../tokens';
+
+/**
+ * A line across the top of a screen saying what is wrong, or what is happening.
+ *
+ * **Cached rows stay undimmed underneath it.** The banner reports a condition; it does not claim
+ * the content below became untrue. Dimming would say the opposite.
+ *
+ * `progress` renders a determinate 3px hairline — omitted entirely rather than shown at zero,
+ * because a bar sitting at zero reads as stuck rather than as not-started.
+ */
+export function Banner({
+  tone = 'info', title, meta, progress, action, actionPlacement = 'trailing', style,
+}: {
+  /** `needsUser` (D3) — waiting on the user (reconnect a toolkit, fill a field), not a failure. */
+  tone?: 'error' | 'sync' | 'info' | 'needsUser';
+  title: string;
+  meta?: string;
+  /** 0–1. */
+  progress?: number;
+  action?: ReactNode;
+  /**
+   * `trailing` (default) puts the action beside the text — right for one short control. `below` puts it under the text,
+   * aligned with it: needed when the action is wide (two buttons, a long label), because beside the text it takes the
+   * whole row and the title and meta collapse to nothing (keyShort's keyboard-setup banner showed only its icon and
+   * buttons, 25 Sep 2026). Optional and default-unchanged for every other app.
+   */
+  actionPlacement?: 'trailing' | 'below';
+  style?: StyleProp<ViewStyle>;
+}) {
+  const { colors } = useDs();
+  const ink: InkToken =
+    tone === 'error' ? 'status.error'
+    : tone === 'sync' ? 'accentInk'
+    : tone === 'needsUser' ? 'status.needsUser'
+    : 'textPrimary';
+  /**
+   * **A banner carries its tone in three places, not only in its title's ink** (14 Sep 2026, product ask: the app read
+   * plain). A tinted ground from the same family, a 3pt edge in the tone's own colour and a leading mark — so the kind of
+   * notice is legible before a word of it is read. `info` takes Solarium's sky (`reference`), which is neither the
+   * accent's live nor a status.
+   */
+  const skin =
+    tone === 'error' ? { ground: colors.statusBg.error, edge: colors.status.error, icon: 'alert' as IconName }
+    : tone === 'sync' ? { ground: colors.accentTint, edge: colors.accentFill, icon: 'refresh' as IconName }
+    : tone === 'needsUser' ? { ground: colors.statusBg.needsUser, edge: colors.status.needsUser, icon: 'alert' as IconName }
+    : { ground: colors.reference.bg, edge: colors.reference.fg, icon: 'info' as IconName };
+  /* Centred only when there is one line and nothing beside it; anything more wants the text to
+     start at the top so the block reads as a paragraph rather than as a floating label. */
+  const below = actionPlacement === 'below' && action != null;
+  const align = progress === undefined && !meta && (!action || below) ? 'center' : 'flex-start';
+
+  return (
+    <Box
+      bg="surface1"
+      lift={1}
+      radius="row"
+      mx="s5"
+      mb="s3"
+      style={[{ backgroundColor: skin.ground, borderLeftWidth: 3, borderLeftColor: skin.edge, overflow: 'hidden' }, style]}>
+      <Box row align={align} justify="space-between" gap="s3" py="s3" px="s4">
+        <Box row flex={1} gap="s3" align={align}>
+          <Box pt={align === 'center' ? undefined : 's1'}>
+            <Icon name={skin.icon} size={16} color={skin.edge} />
+          </Box>
+          <Box flex={1} gap="s1">
+            <Text variant="label" color={ink} style={{ fontWeight: '600' }}>{title}</Text>
+            {meta ? <Text variant="caption" color="textSecondary">{meta}</Text> : null}
+            {below ? <Box pt="s2">{action}</Box> : null}
+          </Box>
+        </Box>
+        {below ? null : action}
+      </Box>
+      {progress === undefined ? null : (
+        <Box height={3} bg="surfaceSunken" style={{ overflow: 'hidden' }}>
+          <Box height={3} bg="accentFill" width={`${Math.round(Math.min(1, Math.max(0, progress)) * 100)}%`} />
+        </Box>
+      )}
+    </Box>
+  );
+}
+
+/**
+ * A small selectable label.
+ *
+ * **Mono by default**, because most chips here carry a machine string — a trigger, a slug, a
+ * field name. `quiet` drops the label to tertiary ink for a set where some members matter less
+ * than others, so the distinction is legible in the row rather than only in a count above it.
+ */
+export function Chip({
+  children, selected = false, mono = true, tone = 'default', onPress,
+}: {
+  children: string;
+  selected?: boolean;
+  mono?: boolean;
+  tone?: 'default' | 'quiet';
+  onPress?: () => void;
+}) {
+  const ink: InkToken = selected ? 'accentInk' : tone === 'quiet' ? 'textTertiary' : 'textSecondary';
+  const body = (
+    <Box
+      alignSelf="flex-start"
+      bg={selected ? 'accentTint' : 'surfaceSunken'}
+      radius="part.pill"
+      px="s3"
+      py="s1">
+      <Text variant="caption" mono={mono} color={ink}>{children}</Text>
+    </Box>
+  );
+  if (!onPress) return body;
+  return <Pressable onPress={onPress} alignSelf="flex-start" aria-label={children}>{body}</Pressable>;
+}

package/src/ds/BrandPreview.tsx

@@ -0,0 +1,159 @@
+import type { ReactNode } from 'react';
+import { Box, Icon, Image, MotionView, Text, useSwap } from '../core';
+import { blockRadii, contrast, useDs } from '../tokens';
+
+/**
+ * **Preview well — five mini mocks of where a brand kit lands (onboarding handoff B10).**
+ *
+ * `appbar` (a workspace's top bar) · `email` (a newsletter header) · `login` (a portal sign-in) ·
+ * `invoice` (an invoice header) · `ticket` (a ticket with its stub and a QR slot).
+ *
+ * **The user's colours appear only inside this well** — that is the handoff's rule, and the reason
+ * this is a block: every other surface in the component stays Solarium. Text laid on a user colour
+ * picks white or ink by `contrast()`, so an unreadable brand colour still produces a readable
+ * preview. The mock cross-fades (M4) whenever what it shows changes.
+ */
+
+export type BrandPreviewKind = 'appbar' | 'email' | 'login' | 'invoice' | 'ticket';
+
+export type BrandPreviewProps = {
+  kind: BrandPreviewKind;
+  brandName: string;
+  /** Valid `#RRGGBB` colours — the primary, and optionally a second (accent / button / link / stub). */
+  colors: string[];
+  /** A font family name — the brand name is set in it. */
+  font?: string;
+  /** An image URI for the logo; without it the brand's initials are drawn. */
+  logoUri?: string;
+};
+
+export function initialsOf(name: string): string {
+  return name.split(/\s+/).filter(Boolean).slice(0, 2).map(w => w[0]!.toUpperCase()).join('');
+}
+
+export function BrandPreview({ kind, brandName, colors: brand, font, logoUri }: BrandPreviewProps) {
+  const { colors } = useDs();
+  const primary = brand[0] ?? colors.textPrimary;
+  const second = brand[1] ?? primary;
+  /* White or ink on a user colour — whichever reads better. */
+  const on = (bg: string) => (contrast(colors.surface1, bg) >= contrast(colors.textPrimary, bg) ? colors.surface1 : colors.textPrimary);
+  const fade = useSwap(`${kind}|${brand.join(',')}|${font ?? ''}|${logoUri ?? ''}`);
+  const nameStyle = { fontFamily: font, fontWeight: '700' as const };
+
+  const Logo = ({ size, ground }: { size: number; ground: string }) => (
+    <Box width={size} height={size} align="center" justify="center" style={{ borderRadius: blockRadii.key, backgroundColor: logoUri ? colors.surface1 : ground, overflow: 'hidden' }}>
+      {logoUri
+        ? <Image source={{ uri: logoUri }} width={size} height={size} resizeMode="contain" alt="" />
+        : <Text style={{ fontSize: Math.round(size * 0.42), fontWeight: '700', color: on(ground) }}>{initialsOf(brandName)}</Text>}
+    </Box>
+  );
+  const Bar = ({ w, tone = colors.band }: { w: `${number}%` | number; tone?: string }) => (
+    <Box height={6} radius="pill" width={w} style={{ backgroundColor: tone }} />
+  );
+  const Pill = ({ bg, label }: { bg: string; label: string }) => (
+    <Box alignSelf="flex-start" px="s3" py="s1" style={{ borderRadius: 6, backgroundColor: bg }}>
+      <Text style={{ fontSize: 11, fontWeight: '600', color: on(bg), fontFamily: font }}>{label}</Text>
+    </Box>
+  );
+  const Paper = ({ children }: { children: ReactNode }) => (
+    <Box style={{ borderRadius: blockRadii.inset, backgroundColor: colors.surface1, borderWidth: 1, borderColor: colors.hairline, overflow: 'hidden' }}>{children}</Box>
+  );
+
+  let mock: ReactNode;
+  if (kind === 'appbar') {
+    mock = (
+      <Paper>
+        <Box row align="center" gap="s2" style={{ backgroundColor: primary, paddingHorizontal: 12, paddingVertical: 10 }}>
+          <Logo size={22} ground={second} />
+          <Text numberOfLines={1} style={{ ...nameStyle, fontSize: 13, color: on(primary), flexShrink: 1 }}>{brandName}</Text>
+          <Box flex={1} />
+          <Box width={20} height={20} radius="pill" style={{ backgroundColor: on(primary), opacity: 0.25 }} />
+        </Box>
+        <Box p="s3" gap="s2">
+          <Bar w="62%" tone={colors.hairlineStrong} />
+          <Bar w="44%" />
+          <Box pt="s1"><Pill bg={second} label="New project" /></Box>
+        </Box>
+      </Paper>
+    );
+  } else if (kind === 'email') {
+    mock = (
+      <Paper>
+        <Box align="center" gap="s1" style={{ backgroundColor: primary, paddingVertical: 14 }}>
+          <Logo size={26} ground={second} />
+          <Text numberOfLines={1} style={{ ...nameStyle, fontSize: 14, color: on(primary) }}>{brandName}</Text>
+        </Box>
+        <Box p="s3" gap="s2">
+          <Bar w="80%" tone={colors.hairlineStrong} />
+          <Bar w="92%" />
+          <Bar w="70%" />
+          <Box pt="s1"><Pill bg={second} label="Read the issue" /></Box>
+        </Box>
+      </Paper>
+    );
+  } else if (kind === 'login') {
+    mock = (
+      <Box align="center" style={{ paddingVertical: 6 }}>
+        <Box style={{ width: '78%', maxWidth: 260 }}>
+          <Paper>
+            <Box p="s3" gap="s2" align="center">
+              <Logo size={28} ground={primary} />
+              <Text numberOfLines={1} style={{ ...nameStyle, fontSize: 13, color: colors.textPrimary }}>{brandName}</Text>
+              <Box height={18} alignSelf="stretch" style={{ borderRadius: 4, borderWidth: 1, borderColor: colors.hairlineStrong }} />
+              <Box height={18} alignSelf="stretch" style={{ borderRadius: 4, borderWidth: 1, borderColor: colors.hairlineStrong }} />
+              <Box alignSelf="stretch" align="center" py="s1" style={{ borderRadius: 6, backgroundColor: primary }}>
+                <Text style={{ fontSize: 11, fontWeight: '600', color: on(primary), fontFamily: font }}>Sign in</Text>
+              </Box>
+              <Text style={{ fontSize: 11, color: second, fontFamily: font, textDecorationLine: 'underline' }}>Forgot password?</Text>
+            </Box>
+          </Paper>
+        </Box>
+      </Box>
+    );
+  } else if (kind === 'invoice') {
+    mock = (
+      <Paper>
+        <Box p="s3" gap="s2">
+          <Box row align="center" gap="s2">
+            <Logo size={24} ground={primary} />
+            <Text numberOfLines={1} style={{ ...nameStyle, fontSize: 13, color: colors.textPrimary, flexShrink: 1 }}>{brandName}</Text>
+            <Box flex={1} />
+            <Text style={{ fontSize: 11, fontWeight: '700', letterSpacing: 1, color: primary, fontFamily: font }}>INVOICE</Text>
+          </Box>
+          <Box height={2} style={{ backgroundColor: primary, borderRadius: 1 }} />
+          <Box row justify="space-between"><Bar w="46%" /><Bar w={36} /></Box>
+          <Box row justify="space-between"><Bar w="38%" /><Bar w={30} /></Box>
+          <Box row justify="space-between" align="center">
+            <Text style={{ fontSize: 11, fontWeight: '600', color: colors.textPrimary, fontFamily: font }}>Total</Text>
+            <Text numeric style={{ fontSize: 12, fontWeight: '700', color: primary, fontFamily: font }}>$4,280.00</Text>
+          </Box>
+        </Box>
+      </Paper>
+    );
+  } else {
+    mock = (
+      <Box row style={{ borderRadius: blockRadii.inset, overflow: 'hidden' }}>
+        <Box flex={1} gap="s1" style={{ backgroundColor: primary, padding: 12, minWidth: 0 }}>
+          <Logo size={22} ground={second} />
+          <Text numberOfLines={1} style={{ ...nameStyle, fontSize: 14, color: on(primary) }}>{brandName}</Text>
+          <Text style={{ fontSize: 11, color: on(primary), fontFamily: font }}>Sat 14 Nov · Gate 2</Text>
+        </Box>
+        <Box width={92} align="center" justify="center" gap="s1" style={{ backgroundColor: second, borderLeftWidth: 2, borderLeftColor: colors.surface1, borderStyle: 'dashed', padding: 8 }}>
+          <Box width={40} height={40} align="center" justify="center" style={{ borderRadius: 4, backgroundColor: colors.surface1 }}>
+            <Icon name="qr" size={28} color={colors.textPrimary} />
+          </Box>
+          <Text style={{ fontSize: 10, fontWeight: '600', color: on(second), fontFamily: font }}>ADMIT ONE</Text>
+        </Box>
+      </Box>
+    );
+  }
+
+  return (
+    <Box
+      role="img"
+      aria-label={`Preview: ${brandName}, ${kind}`}
+      style={{ borderRadius: blockRadii.mid, backgroundColor: colors.surfaceSunken, padding: 12 }}>
+      <MotionView style={{ opacity: fade }}>{mock}</MotionView>
+    </Box>
+  );
+}

package/src/ds/Button.tsx

@@ -0,0 +1,181 @@
+import type { StyleProp, ViewStyle } from 'react-native';
+import { useState, type ReactNode } from 'react';
+
+import {
+  isAndroid, kindChipSize, layout, radii, useDs, type Kind, type Status,
+} from '../tokens';
+import { Box, Icon, Pressable, Text, inkHex, type IconName, type InkToken } from '../core';
+
+export type ButtonVariant = 'primary' | 'secondary' | 'brand' | 'outline' | 'ghost' | 'danger';
+/** `xsmall` is Solarium's small ghost (28px, 12/600) — Undo, Try again, Copy inside a row. */
+export type ButtonSize = 'xsmall' | 'small' | 'medium' | 'large';
+
+export type ButtonProps = {
+  children: string;
+  variant?: ButtonVariant;
+  size?: ButtonSize;
+  fullWidth?: boolean;
+  disabled?: boolean;
+  leadingGlyph?: IconName;
+  /** Working — an operation this button started is in flight. Announced as `aria-busy`. */
+  busy?: boolean;
+  onPress?: () => void;
+  style?: StyleProp<ViewStyle>;
+  /** The accessible name when the visible label is not enough on its own — "Connect Outlook"
+      beside two other "Connect" buttons. Defaults to the label. */
+  'aria-label'?: string;
+  /** A disclosure button — "Filters · 2" opening a panel (batch 3's Filter Panel). */
+  'aria-expanded'?: boolean;
+  'aria-controls'?: string;
+};
+
+const SIZES: Record<ButtonSize, { padH: number; fontSize: number; minHeight: number }> = {
+  xsmall: { padH: 10, fontSize: 12, minHeight: 28 },
+  small: { padH: 16, fontSize: 13, minHeight: 36 },
+  medium: { padH: 20, fontSize: 15, minHeight: layout.touchTargetMin },
+  large: { padH: 24, fontSize: 16, minHeight: layout.ctaHeight },
+};
+
+/**
+ * **Solarium 0.2.0's Button (C13): 8px corners, never a pill; one coral primary per view.**
+ *
+ * Changed on 2026-09-24 (`docs/DECISIONS.md` §7, "Solarium 0.2.0 reconciliation"), for every theme:
+ * - **Shape.** `--r-inset` (8px). 0.2.0 locked decision 18: *"Pressable actions use the radius ladder,
+ *   not pills."* The pill and its coloured `liftAccent` shadow are gone — 0.2.0 allows `--lift-1`
+ *   and `--lift-2` only, and a primary is a fill, not an object that floats.
+ * - **Primary** fills with `--action-bg` (`accentFill`) and deepens to `--action-bg-hover`
+ *   (`accentInk`) on hover and while busy; disabled is the line-soft ground with muted ink — a
+ *   disabled primary that only fades still reads as the thing to press. **Busy outranks disabled**
+ *   (25 Sep 2026): busy + disabled is deep coral, still non-interactive.
+ * - **Secondary is 0.2.0's "ghost"**: white, a 1px `--line` edge, ink text, the well on hover.
+ *   `ghost` here stays ink on nothing (a tertiary), `outline` an accent-ink edge.
+ * - **Press** is scale .98 (M8), never a colour change.
+ *
+ * Not built on `Pressable`'s square hit target: this is a stretchable control with a scale press.
+ */
+/** Ink and ground per variant. Every entry is a TOKEN NAME — see `core/roles.ts`. */
+const SKIN: Record<ButtonVariant, {
+  bg?: 'surface1' | 'accentTint';
+  fg: InkToken;
+  edge?: 'outline';
+}> = {
+  /* No `bg` token: the fill is `useDs().action.bg`, resolved below. */
+  primary: { fg: 'accentOnFill' },
+  secondary: { bg: 'surface1', fg: 'textPrimary' },
+  brand: { bg: 'accentTint', fg: 'accentInk' },
+  outline: { bg: 'surface1', fg: 'accentInk', edge: 'outline' },
+  /* Ink on nothing: leaving is not an accent action, and a filled red button invites the tap it
+     is warning about. */
+  ghost: { fg: 'textPrimary' },
+  danger: { fg: 'status.error' },
+};
+
+export function Button({
+  children, variant = 'secondary', size = 'medium',
+  fullWidth = false, disabled = false, leadingGlyph, busy, onPress, style, 'aria-label': ariaLabel,
+  'aria-expanded': ariaExpanded, 'aria-controls': ariaControls,
+}: ButtonProps) {
+  const { colors, action } = useDs();
+  const [hovered, setHovered] = useState(false);
+  const s = SIZES[size];
+  const v = SKIN[variant];
+  const primary = variant === 'primary';
+  const secondary = variant === 'secondary';
+  const hover = hovered && !disabled;
+  /* Busy outranks disabled in how a primary LOOKS: a button whose operation is in flight is deep
+     coral with `aria-busy` (Solarium 0.2.0; batch 3 §C13), even when the caller also disables it
+     to stop a second press. It stays non-interactive — `disabled` still reaches the Pressable. */
+  const busyPrimary = primary && Boolean(busy);
+  const ink: InkToken = primary && disabled && !busyPrimary ? 'textSecondary' : v.fg;
+
+  return (
+    <Pressable
+      onPress={onPress}
+      onHoverIn={primary || secondary ? () => setHovered(true) : undefined}
+      onHoverOut={primary || secondary ? () => setHovered(false) : undefined}
+      disabled={disabled}
+      aria-busy={busy || undefined}
+      aria-expanded={ariaExpanded}
+      aria-controls={ariaControls}
+      row
+      gap="s2"
+      radius="field"
+      bg={v.bg}
+      edge={v.edge}
+      /* Press is scale ONLY (M8) — never a colour change, never an opacity dip. */
+      press="scale"
+      minHeight={s.minHeight}
+      alignSelf={fullWidth ? 'stretch' : 'flex-start'}
+      style={[
+        { paddingHorizontal: s.padH },
+        primary && {
+          backgroundColor: busyPrimary ? action.bgHover : disabled ? colors.band : hover ? action.bgHover : action.bg,
+          /* A disabled primary is the line-soft ground, not a faded primary. */
+          opacity: 1,
+        },
+        secondary && { boxShadow: `0 0 0 1px ${colors.hairlineStrong}`, backgroundColor: hover ? colors.surfaceSunken : colors.surface1 },
+        style,
+      ]}
+      aria-label={ariaLabel ?? children}>
+      {leadingGlyph ? <Icon name={leadingGlyph} size={16} color={inkHex(colors, ink)} /> : null}
+      <Text color={ink} numberOfLines={1} style={{ fontSize: s.fontSize, fontWeight: '600' }}>
+        {children}
+      </Text>
+    </Pressable>
+  );
+}
+
+/**
+ * A line of meta under something.
+ *
+ * **No `warning` tone yet, though the system has one now.** `status.needsUser` exists since D3
+ * (11 Sep 2026), but nothing has asked this component for it — adding the prop belongs to
+ * whichever screen task needs it first, not to the token change that made it possible. Pending
+ * work with nothing to flag is still informational and takes meta ink. `success` is the accent,
+ * which means just-happened.
+ */
+export function Caption({
+  children, tone,
+}: { children: ReactNode; tone?: 'danger' | 'success' }) {
+  const color: InkToken =
+    tone === 'danger' ? 'status.error' : tone === 'success' ? 'accentInk' : 'textTertiary';
+  return <Text variant="caption" color={color}>{children}</Text>;
+}
+
+const STATUS_WORD: Record<Status, string> = {
+  executed: 'Executed', running: 'Running', queued: 'Queued', error: 'Failed',
+  needsUser: 'Needs you',
+};
+
+/** The status word. **The dot beside it is redundant by design** — the word carries it. */
+export function StatusLabel({
+  status, children,
+}: { status: Status; children?: string }) {
+  return (
+    <Text variant="caption" color={`status.${status}`}>{children ?? STATUS_WORD[status]}</Text>
+  );
+}
+
+/**
+ * The kind mark — **the one place colour is allowed**, per the contract: *colour lives in the
+ * leading chip and nowhere else*. Rows are never tinted by kind.
+ *
+ * Android renders a circle, iOS a squircle; Solarium is a rounded square on both, because a
+ * circle there would make the one tinted object in a row read as an avatar.
+ */
+export function KindChip({ kind = 'text', size }: { kind?: Kind; size?: number }) {
+  const { colors, theme } = useDs();
+  const s = size ?? kindChipSize;
+  const sol = theme === 'solarium';
+  return (
+    <Box
+      width={s}
+      height={s}
+      align="center"
+      justify="center"
+      bg={`kindBg.${kind}`}
+      style={{ borderRadius: sol ? 9 : isAndroid ? s / 2 : radii.chip }}>
+      <Icon name={kind} size={Math.round(s * 0.5)} color={colors.kind[kind].fg} />
+    </Box>
+  );
+}