@starcier/create-builder 0.0.0-stage → 1.0.0-next.1

package/template/src/design-system/components/Button/button.css

@@ -0,0 +1,62 @@
+.ds-button {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  gap: var(--space-s);
+  min-height: 24px;
+  border: 1px solid transparent;
+  border-radius: var(--radius-s);
+  font-family: var(--font-sans);
+  font-size: var(--text-label-size);
+  font-weight: var(--text-label-weight);
+  line-height: var(--text-label-line);
+  cursor: pointer;
+  transition: background-color 120ms ease, border-color 120ms ease;
+}
+
+.ds-button:focus-visible {
+  outline: 2px solid var(--color-border-focus);
+  outline-offset: 2px;
+}
+
+.ds-button:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+
+.ds-button--medium {
+  padding: var(--space-s) var(--space-l);
+}
+
+.ds-button--small {
+  padding: var(--space-2xs) var(--space-m);
+}
+
+.ds-button--primary {
+  background: var(--color-accent-default);
+  color: var(--color-text-inverse);
+}
+
+.ds-button--primary:hover:not(:disabled) {
+  background: var(--color-accent-hover);
+}
+
+.ds-button--secondary {
+  background: var(--color-bg-surface);
+  border-color: var(--color-border-strong);
+  color: var(--color-text-primary);
+}
+
+.ds-button--secondary:hover:not(:disabled) {
+  background: var(--color-bg-surface-muted);
+}
+
+.ds-button--ghost {
+  background: transparent;
+  color: var(--color-text-secondary);
+}
+
+.ds-button--ghost:hover:not(:disabled) {
+  background: var(--color-bg-surface-muted);
+  color: var(--color-text-primary);
+}

package/template/src/design-system/components/Button/index.ts

@@ -0,0 +1 @@
+export { Button, type ButtonProps, type ButtonSize, type ButtonVariant } from './Button';

package/template/src/design-system/components/Card/Card.tsx

@@ -0,0 +1,22 @@
+import type { HTMLAttributes, ReactNode } from 'react';
+import './card.css';
+
+export interface CardProps extends Omit<HTMLAttributes<HTMLElement>, 'title'> {
+  title?: ReactNode;
+  /** Shown under the title, in secondary text. */
+  description?: ReactNode;
+}
+
+export function Card({ title, description, className, children, ...rest }: CardProps) {
+  return (
+    <section className={['ds-card', className].filter(Boolean).join(' ')} {...rest}>
+      {(title || description) && (
+        <header className="ds-card__header">
+          {title && <h2 className="ds-card__title">{title}</h2>}
+          {description && <p className="ds-card__description">{description}</p>}
+        </header>
+      )}
+      {children}
+    </section>
+  );
+}

package/template/src/design-system/components/Card/card.css

@@ -0,0 +1,27 @@
+.ds-card {
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-l);
+  padding: var(--space-2xl);
+  background: var(--color-bg-surface);
+  border: 1px solid var(--color-border-default);
+  border-radius: var(--radius-m);
+}
+
+.ds-card__header {
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-2xs);
+}
+
+.ds-card__title {
+  margin: 0;
+  font-size: var(--text-title-size);
+  font-weight: var(--text-title-weight);
+  line-height: var(--text-title-line);
+}
+
+.ds-card__description {
+  margin: 0;
+  color: var(--color-text-secondary);
+}

package/template/src/design-system/components/Card/index.ts

@@ -0,0 +1 @@
+export { Card, type CardProps } from './Card';

package/template/src/design-system/components/Field/Field.tsx

@@ -0,0 +1,28 @@
+import { useId, type InputHTMLAttributes } from 'react';
+import './field.css';
+
+export interface FieldProps extends InputHTMLAttributes<HTMLInputElement> {
+  label: string;
+  /** Shown under the input, in secondary text. */
+  hint?: string;
+}
+
+/** A labelled text input. The `.ds-field` wrapper is what the review layer recognises. */
+export function Field({ label, hint, id, className, ...rest }: FieldProps) {
+  const generated = useId();
+  const inputId = id ?? generated;
+  const hintId = hint ? `${inputId}-hint` : undefined;
+  return (
+    <div className={['ds-field', className].filter(Boolean).join(' ')}>
+      <label className="ds-field__label" htmlFor={inputId}>
+        {label}
+      </label>
+      <input id={inputId} className="ds-field__input" aria-describedby={hintId} {...rest} />
+      {hint && (
+        <span id={hintId} className="ds-field__hint">
+          {hint}
+        </span>
+      )}
+    </div>
+  );
+}

package/template/src/design-system/components/Field/field.css

@@ -0,0 +1,37 @@
+.ds-field {
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-2xs);
+}
+
+.ds-field__label {
+  font-size: var(--text-label-size);
+  font-weight: var(--text-label-weight);
+  line-height: var(--text-label-line);
+}
+
+.ds-field__input {
+  padding: var(--space-s) var(--space-m);
+  background: var(--color-bg-surface);
+  border: 1px solid var(--color-border-strong);
+  border-radius: var(--radius-s);
+  color: var(--color-text-primary);
+  font-family: var(--font-sans);
+  font-size: var(--text-body-size);
+  line-height: var(--text-body-line);
+}
+
+.ds-field__input::placeholder {
+  color: var(--color-text-secondary);
+}
+
+.ds-field__input:focus-visible {
+  outline: 2px solid var(--color-border-focus);
+  outline-offset: 1px;
+}
+
+.ds-field__hint {
+  color: var(--color-text-secondary);
+  font-size: var(--text-caption-size);
+  line-height: var(--text-caption-line);
+}

package/template/src/design-system/components/Field/index.ts

@@ -0,0 +1 @@
+export { Field, type FieldProps } from './Field';

package/template/src/design-system/components/Modal/Modal.tsx

@@ -0,0 +1,55 @@
+import { useEffect, useId, useRef, type HTMLAttributes, type ReactNode } from 'react';
+import { createPortal } from 'react-dom';
+import './modal.css';
+
+export interface ModalProps extends Omit<HTMLAttributes<HTMLDivElement>, 'title'> {
+  open: boolean;
+  onClose(): void;
+  title: ReactNode;
+  /** Buttons along the bottom, right-aligned. */
+  footer?: ReactNode;
+}
+
+/**
+ * A dialog over a scrim, rendered at the end of the document. Escape and a
+ * click on the scrim close it. Its root carries `.ds-modal`, which the builder
+ * passes to the review layer as an overlay (see `App.tsx`).
+ */
+export function Modal({ open, onClose, title, footer, children, className, ...rest }: ModalProps) {
+  const titleId = useId();
+  const dialogRef = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    if (!open) return;
+    dialogRef.current?.focus();
+    const onKey = (event: KeyboardEvent) => {
+      if (event.key === 'Escape') onClose();
+    };
+    document.addEventListener('keydown', onKey);
+    return () => document.removeEventListener('keydown', onKey);
+  }, [open, onClose]);
+
+  if (!open) return null;
+
+  return createPortal(
+    <div className="ds-modal" onClick={onClose}>
+      <div
+        ref={dialogRef}
+        role="dialog"
+        aria-modal="true"
+        aria-labelledby={titleId}
+        tabIndex={-1}
+        className={['ds-modal__dialog', className].filter(Boolean).join(' ')}
+        onClick={(event) => event.stopPropagation()}
+        {...rest}
+      >
+        <h2 id={titleId} className="ds-modal__title">
+          {title}
+        </h2>
+        <div className="ds-modal__body">{children}</div>
+        {footer && <div className="ds-modal__footer">{footer}</div>}
+      </div>
+    </div>,
+    document.body,
+  );
+}

package/template/src/design-system/components/Modal/index.ts

@@ -0,0 +1 @@
+export { Modal, type ModalProps } from './Modal';

package/template/src/design-system/components/Modal/modal.css

@@ -0,0 +1,39 @@
+/* Above the builder's top bar (200), below its comments and tours (9140 up). */
+.ds-modal {
+  position: fixed;
+  inset: 0;
+  z-index: var(--z-modal);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  padding: var(--space-2xl);
+  background: var(--color-scrim);
+}
+
+.ds-modal__dialog {
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-l);
+  width: min(480px, 100%);
+  padding: var(--space-2xl);
+  background: var(--color-bg-surface);
+  border-radius: var(--radius-l);
+  box-shadow: var(--color-shadow-l);
+}
+
+.ds-modal__dialog:focus {
+  outline: none;
+}
+
+.ds-modal__title {
+  margin: 0;
+  font-size: var(--text-title-size);
+  font-weight: var(--text-title-weight);
+  line-height: var(--text-title-line);
+}
+
+.ds-modal__footer {
+  display: flex;
+  justify-content: flex-end;
+  gap: var(--space-s);
+}

package/template/src/design-system/components/ThemeToggle/ThemeToggle.tsx

@@ -0,0 +1,13 @@
+import { useTheme } from '../../theme';
+import { Button } from '../Button';
+
+/** Switches between the light and dark themes. Shown in the builder's top bar. */
+export function ThemeToggle() {
+  const { theme, toggle } = useTheme();
+  const next = theme === 'light' ? 'dark' : 'light';
+  return (
+    <Button variant="ghost" size="small" onClick={toggle} aria-label={`Switch to ${next} theme`}>
+      {theme === 'light' ? 'Dark theme' : 'Light theme'}
+    </Button>
+  );
+}

package/template/src/design-system/components/ThemeToggle/index.ts

@@ -0,0 +1 @@
+export { ThemeToggle } from './ThemeToggle';

package/template/src/design-system/global.css

@@ -0,0 +1,26 @@
+/* Document-wide defaults. The custom properties are set by ThemeProvider. */
+
+*,
+*::before,
+*::after {
+  box-sizing: border-box;
+}
+
+body {
+  margin: 0;
+  background: var(--color-bg-page);
+  color: var(--color-text-primary);
+  font-family: var(--font-sans);
+  font-size: var(--text-body-size);
+  line-height: var(--text-body-line);
+  -webkit-font-smoothing: antialiased;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  *,
+  *::before,
+  *::after {
+    transition-duration: 0s !important;
+    animation-duration: 0s !important;
+  }
+}

package/template/src/design-system/palette.ts

@@ -0,0 +1,40 @@
+import type { BuilderPalette } from '@starcier/collab-ui';
+import { colors, radius, space, typography, type ThemeName } from './tokens';
+
+/**
+ * Maps this design system's tokens onto `BuilderPalette`, the one visual
+ * contract between a builder and the Starcier packages. It colours the
+ * builder's chrome — the catalogue, the top bar, sign-in, the share and invite
+ * pages — so they look like this product.
+ *
+ * Comment pins and guided tours do not use it: they keep a fixed look of their
+ * own in every builder, on purpose.
+ *
+ * Change the right-hand sides when the tokens change; the left-hand slot names
+ * are the contract and stay as they are.
+ */
+export function resolveBuilderPalette(theme: ThemeName): BuilderPalette {
+  const c = colors[theme];
+  return {
+    pageBg: c.bg.page,
+    panel: c.bg.surface,
+    panelMuted: c.bg.surfaceMuted,
+    border: c.border.default,
+    borderAccent: c.border.focus,
+    textPrimary: c.text.primary,
+    textSecondary: c.text.secondary,
+    textAccent: c.text.accent,
+    textInverse: c.text.inverse,
+    accent: c.accent.default,
+    accentHover: c.accent.hover,
+    accentSubtle: c.accent.subtle,
+    scrim: c.scrim,
+    status: c.status,
+    shadow: c.shadow,
+    space,
+    // The contract has five steps below `full`; this scale has four, so the
+    // two smallest share a value.
+    radius: { '2xs': radius.xs, xs: radius.xs, s: radius.s, m: radius.m, l: radius.l, full: radius.full },
+    type: typography,
+  };
+}

package/template/src/design-system/theme.ts

@@ -0,0 +1,55 @@
+import { createContext, useContext } from 'react';
+import { colors, fontFamily, radius, space, typography, zIndex, type ThemeName } from './tokens';
+
+export const THEME_STORAGE_KEY = 'builder-theme';
+
+export interface ThemeValue {
+  theme: ThemeName;
+  toggle(): void;
+}
+
+export const ThemeContext = createContext<ThemeValue>({ theme: 'light', toggle: () => {} });
+
+/** The active theme, and a way to switch it. */
+export function useTheme(): ThemeValue {
+  return useContext(ThemeContext);
+}
+
+/** The theme saved in this browser, or else the system's preference. */
+export function initialTheme(): ThemeName {
+  try {
+    const saved = localStorage.getItem(THEME_STORAGE_KEY);
+    if (saved === 'light' || saved === 'dark') return saved;
+  } catch {
+    /* storage unavailable: fall through to the system setting */
+  }
+  return window.matchMedia?.('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
+}
+
+/**
+ * Every token as a CSS custom property, so component stylesheets can use
+ * `var(--color-accent-default)` and switch with the theme. Names follow the
+ * token paths: `colors.bg.page` → `--color-bg-page`, `space.m` → `--space-m`.
+ */
+export function cssVariables(theme: ThemeName): Record<string, string> {
+  const vars: Record<string, string> = {};
+  const flatten = (prefix: string, value: unknown) => {
+    if (typeof value === 'string') vars[prefix] = value;
+    else if (value && typeof value === 'object') {
+      for (const [key, inner] of Object.entries(value)) flatten(`${prefix}-${key}`, inner);
+    }
+  };
+  flatten('--color', colors[theme]);
+  flatten('--space', space);
+  flatten('--radius', radius);
+  flatten('--font', fontFamily);
+  for (const [role, style] of Object.entries(typography)) {
+    vars[`--text-${role}-size`] = style.fontSize;
+    vars[`--text-${role}-weight`] = String(style.fontWeight);
+    vars[`--text-${role}-line`] = style.lineHeight;
+    vars[`--text-${role}-tracking`] = style.letterSpacing;
+    vars[`--text-${role}-case`] = style.textTransform;
+  }
+  vars['--z-modal'] = String(zIndex.modal);
+  return vars;
+}

package/template/src/design-system/tokens.ts

@@ -0,0 +1,126 @@
+/**
+ * The design tokens: the single source of every colour, size and text style in
+ * this builder. A neutral starting point; replace the values with your own
+ * design system's, keep the names, and everything follows.
+ *
+ * Colours come in a light and a dark set with identical keys. The rest is
+ * shared by both themes.
+ */
+
+export type ThemeName = 'light' | 'dark';
+
+interface StatusColor {
+  /** Soft tinted surface for pills and banners. */
+  surface: string;
+  /** Solid colour for icons, text and fills. */
+  accent: string;
+  border: string;
+}
+
+export interface ColorTokens {
+  bg: { page: string; surface: string; surfaceMuted: string };
+  border: { default: string; strong: string; focus: string };
+  text: { primary: string; secondary: string; accent: string; inverse: string };
+  accent: { default: string; hover: string; subtle: string };
+  status: { info: StatusColor; success: StatusColor; warning: StatusColor; danger: StatusColor };
+  scrim: string;
+  shadow: { s: string; l: string };
+}
+
+export const colors: Record<ThemeName, ColorTokens> = {
+  light: {
+    bg: { page: '#F7F7F8', surface: '#FFFFFF', surfaceMuted: '#EFEFF2' },
+    border: { default: '#DCDCE2', strong: '#B6B6C0', focus: '#4F46E5' },
+    text: { primary: '#16161A', secondary: '#5B5B66', accent: '#4338CA', inverse: '#FFFFFF' },
+    accent: { default: '#4F46E5', hover: '#4338CA', subtle: '#EEEEFD' },
+    status: {
+      info: { surface: '#E8F1FD', accent: '#1F6FD1', border: '#1F6FD1' },
+      success: { surface: '#E5F5EA', accent: '#1C8A45', border: '#1C8A45' },
+      warning: { surface: '#FDF1DE', accent: '#A8620C', border: '#A8620C' },
+      danger: { surface: '#FCE7E7', accent: '#C23434', border: '#C23434' },
+    },
+    scrim: 'rgba(22, 22, 26, 0.5)',
+    shadow: { s: '0 2px 6px rgba(22, 22, 26, 0.16)', l: '0 12px 32px rgba(22, 22, 26, 0.2)' },
+  },
+  dark: {
+    bg: { page: '#111114', surface: '#1B1B20', surfaceMuted: '#26262D' },
+    border: { default: '#34343D', strong: '#4A4A55', focus: '#8B85FF' },
+    text: { primary: '#F2F2F5', secondary: '#A6A6B2', accent: '#A5A0FF', inverse: '#111114' },
+    accent: { default: '#8B85FF', hover: '#A5A0FF', subtle: '#25234A' },
+    status: {
+      info: { surface: '#16273D', accent: '#6CA8F0', border: '#6CA8F0' },
+      success: { surface: '#15301F', accent: '#5FCB86', border: '#5FCB86' },
+      warning: { surface: '#36280F', accent: '#E8A64A', border: '#E8A64A' },
+      danger: { surface: '#3A1919', accent: '#F07676', border: '#F07676' },
+    },
+    scrim: 'rgba(0, 0, 0, 0.6)',
+    shadow: { s: '0 2px 6px rgba(0, 0, 0, 0.4)', l: '0 12px 32px rgba(0, 0, 0, 0.5)' },
+  },
+};
+
+/** Spacing scale, smallest to largest. */
+export const space = {
+  '3xs': '2px',
+  '2xs': '4px',
+  xs: '6px',
+  s: '8px',
+  m: '12px',
+  l: '16px',
+  xl: '20px',
+  '2xl': '24px',
+  '3xl': '32px',
+  '4xl': '40px',
+} as const;
+
+/** Corner radii. */
+export const radius = {
+  xs: '4px',
+  s: '6px',
+  m: '10px',
+  l: '16px',
+  full: '9999px',
+} as const;
+
+export const fontFamily = {
+  sans: 'system-ui, -apple-system, "Segoe UI", Roboto, sans-serif',
+  mono: 'ui-monospace, SFMono-Regular, Menlo, Consolas, monospace',
+} as const;
+
+export interface TextStyle {
+  fontFamily: string;
+  fontSize: string;
+  fontWeight: number;
+  lineHeight: string;
+  letterSpacing: string;
+  /** Kept to what every supported `@starcier/collab-ui` accepts in `BuilderTextStyle`. */
+  textTransform: 'none' | 'uppercase';
+}
+
+const text = (
+  family: string,
+  fontWeight: number,
+  fontSize: string,
+  lineHeight: string,
+  textTransform: TextStyle['textTransform'] = 'none',
+  letterSpacing = '0px',
+): TextStyle => ({ fontFamily: family, fontWeight, fontSize, lineHeight, letterSpacing, textTransform });
+
+/** Text styles by role. */
+export const typography = {
+  heading: text(fontFamily.sans, 600, '28px', '36px'),
+  title: text(fontFamily.sans, 600, '18px', '24px'),
+  body: text(fontFamily.sans, 400, '14px', '20px'),
+  label: text(fontFamily.sans, 500, '14px', '20px'),
+  caption: text(fontFamily.sans, 400, '12px', '16px'),
+  overline: text(fontFamily.sans, 600, '11px', '16px', 'uppercase', '0.06em'),
+  mono: text(fontFamily.mono, 500, '13px', '20px'),
+} as const;
+
+/**
+ * Stacking order. The prototype builder's top bar sits at 200 and its
+ * comments and tours from 9140 up, so overlays live between the two: above the
+ * bar, below the collaboration layer.
+ */
+export const zIndex = {
+  modal: 1000,
+} as const;

package/template/src/main.tsx

@@ -0,0 +1,13 @@
+import { StrictMode } from 'react';
+import { createRoot } from 'react-dom/client';
+import { BrowserRouter } from 'react-router';
+import { App } from './App';
+import './design-system/global.css';
+
+createRoot(document.getElementById('root')!).render(
+  <StrictMode>
+    <BrowserRouter>
+      <App />
+    </BrowserRouter>
+  </StrictMode>,
+);

package/template/src/prototypes/getting-started/welcome/README.md

@@ -0,0 +1,6 @@
+# Welcome
+
+The example prototype: a small dashboard and a form that opens a dialog. It exists to show the
+shape of a prototype folder; copy it for new prototypes, then delete it.
+
+Workflows: **Welcome walkthrough** — the summary, the form (filled in for you) and its dialog.

package/template/src/prototypes/getting-started/welcome/Welcome.tsx

@@ -0,0 +1,74 @@
+import { useState } from 'react';
+import { Button } from '../../../design-system/components/Button';
+import { Card } from '../../../design-system/components/Card';
+import { Field } from '../../../design-system/components/Field';
+import { Modal } from '../../../design-system/components/Modal';
+import { stats } from './data';
+import './welcome.css';
+
+/**
+ * The example prototype: a small dashboard and a form that opens a dialog.
+ * Copy its shape for new prototypes, then delete it.
+ */
+export function Welcome() {
+  const [name, setName] = useState('');
+  const [email, setEmail] = useState('');
+  const [confirming, setConfirming] = useState(false);
+
+  return (
+    <div className="welcome">
+      <header className="welcome__header" data-tour="welcome-header">
+        <span className="welcome__overline">Getting started</span>
+        <h1 className="welcome__title">Welcome</h1>
+        <p className="welcome__lead">An example prototype. Replace it with your own screens.</p>
+      </header>
+
+      <div className="welcome__stats" data-tour="welcome-stats">
+        {stats.map((stat) => (
+          <Card key={stat.id}>
+            <span className="welcome__stat-label">{stat.label}</span>
+            <span className="welcome__stat-value">{stat.value}</span>
+            <span className="welcome__stat-note">{stat.note}</span>
+          </Card>
+        ))}
+      </div>
+
+      <Card title="Request access" description="Fill in the form and review your request." data-tour="welcome-form">
+        <div className="welcome__form">
+          <Field label="Name" placeholder="Ana Example" value={name} onChange={(e) => setName(e.target.value)} />
+          <Field
+            label="Work email"
+            type="email"
+            placeholder="ana@example.com"
+            value={email}
+            onChange={(e) => setEmail(e.target.value)}
+          />
+          <div>
+            <Button data-tour="welcome-review" disabled={!name || !email} onClick={() => setConfirming(true)}>
+              Review request
+            </Button>
+          </div>
+        </div>
+      </Card>
+
+      <Modal
+        open={confirming}
+        onClose={() => setConfirming(false)}
+        title="Send this request?"
+        data-tour="welcome-modal"
+        footer={
+          <>
+            <Button variant="secondary" onClick={() => setConfirming(false)}>
+              Cancel
+            </Button>
+            <Button onClick={() => setConfirming(false)}>Send request</Button>
+          </>
+        }
+      >
+        <p className="welcome__summary">
+          {name || 'Your name'} · {email || 'your email'}
+        </p>
+      </Modal>
+    </div>
+  );
+}

package/template/src/prototypes/getting-started/welcome/data.ts

@@ -0,0 +1,14 @@
+/** Mock data for the Welcome prototype. Static and local: prototypes never call a backend. */
+
+export interface Stat {
+  id: string;
+  label: string;
+  value: string;
+  note: string;
+}
+
+export const stats: readonly Stat[] = [
+  { id: 'projects', label: 'Active projects', value: '12', note: '3 started this month' },
+  { id: 'reviews', label: 'Open reviews', value: '5', note: '2 waiting on you' },
+  { id: 'shipped', label: 'Shipped this quarter', value: '27', note: 'Up from 19 last quarter' },
+];

package/template/src/prototypes/getting-started/welcome/index.ts

@@ -0,0 +1,2 @@
+export { Welcome } from './Welcome';
+export { welcomeTour } from './workflows';