lecodes-sdk 0.19.0

package/prompts/design.md

@@ -0,0 +1,218 @@
+# Design rules
+
+## Folder layout
+
+```
+design/
+  screens/<id>.ts    one file = one screen; default-exports the screen; the FILENAME is its identity
+  shared/tokens.ts   the brand: colors, spacing, radius, type scale — every screen's only source of values
+  shared/ui.ts       the component kit: buttons, fields, cards, sheets — screens compose these
+  shared/tabs.ts     the app's tab bar, declared ONCE via defineTabs (see below)
+  meta.json          the app map: descriptions, roles, groups, edges — READ here, WRITE via design_map
+  spec.md            the concept narrative: data model, actors, rules & decisions
+  assets/            vendored icons/fonts and images (listed under [Assets])
+```
+
+## Build the brand kit first
+
+A design that looks designed starts from a kit, not from screens. On a new design, before the first
+screen: `shared/tokens.ts` (a real palette — surfaces, text tiers, one or two accents, status
+colors; a spacing/radius/type scale), then `shared/ui.ts` with the components the app will clearly
+need. The kit outlives the design: when the app is built, it IMPORTS `shared/tokens.ts` (and the
+presentational components of `shared/ui.ts`) unchanged — so build tokens on `theme()`, one live
+table for design and app alike, and shape components as things worth keeping. Screens then read as
+composition:
+
+```ts
+// design/shared/tokens.ts — surfaces dark-to-light, text in tiers, accents as a family.
+// ONE theme() call registers the vars and returns the accessors ("var(--x)" strings); the system
+// key `color` in the same table sets the app-wide default text color. Re-calling theme() with new
+// values (dark mode, brand swap) restyles every screen — and later the built app — live.
+const palette = {
+  bg: "#080808", card: "#161618", cardAlt: "#1d1d20", field: "#101012",
+  border: "#2a2a2e", text: "#ffffff", muted: "#8a8a93", faint: "#5a5b62",
+  accent: "#00BFC2", accentPressed: "#00999b", accentDeep: "#0c4e4f", onAccent: "#05201f",
+  success: "#30D158", danger: "#F83131", scrim: "#000000b3",
+  // theme SYSTEM keys — SDK-rendered chrome reads these. `color` = default text color everywhere;
+  // the other four brand the tab bar (defineTabs here, UITabs in the built app). Mirror the brand:
+  color: "#ffffff",
+  primaryColor: "#00BFC2", mutedColor: "#8a8a93", tabbarBg: "#161618", screenBg: "#080808",
+}
+export const colors: { [K in keyof typeof palette]: string } = theme(palette)
+export const spacing = { xs: 4, sm: 8, md: 12, lg: 16, xl: 20, xxl: 24 }
+export const radius = { sm: 8, md: 12, lg: 16, pill: 999 }
+```
+
+```ts
+// design/shared/ui.ts — excerpts; the kit grows with the design
+import { colors, spacing, radius } from "./tokens"
+
+export const PrimaryButton = (label: string, o: { name?: string, disabled?: boolean } = {}) =>
+  UIButton(UIText(label).style({ fontSize: 16, fontWeight: 700, color: o.disabled ? colors.muted : colors.onAccent }))
+    .style({ height: 52, borderRadius: radius.md, bgColor: o.disabled ? colors.accentDeep : colors.accent,
+             justifyContent: "center", alignItems: "center", name: o.name, onPressed: { bgColor: colors.accentPressed } })
+
+export const SectionLabel = (t: string) =>
+  UIText(t.toUpperCase()).style({ fontSize: 11, fontWeight: 600, letterSpacing: 2, color: colors.faint })
+
+// A field is a STATIC MOCK — the value is drawn as text (see ui rules); passwords as dots.
+export const Field = (o: { label?: string, value?: string, placeholder?: string, focused?: boolean }) =>
+  UIColumn(
+    o.label ? SectionLabel(o.label) : null,
+    UIRow(UIText(o.value ?? o.placeholder ?? "").style({ flexGrow: 1, fontSize: 16, color: o.value ? colors.text : colors.muted }))
+      .style({ height: 52, px: 16, alignItems: "center", bgColor: colors.field, borderRadius: radius.md,
+               border: `1px solid ${o.focused ? colors.accent : colors.border}` }),
+  ).style({ gap: spacing.sm })
+
+// Bottom sheet shell — a real modal: the scrim is overlayColor, the box is just the bottom stack.
+export const Sheet = (...children: UINodeChild[]) => {
+  const sheet = UIWidget(children).style({
+    left: 0, right: 0, bottom: 0, px: spacing.lg, pb: "calc(safe-bottom + 16px)", gap: spacing.sm,
+    overlayColor: colors.scrim,
+  })
+  return sheet.onOverlayTap(() => sheet.hide())
+}
+
+// Full-screen confirm — full-inset box, centered card, NO onOverlayTap (a confirm demands a choice).
+export const ConfirmDialog = (o: { title: string, body?: string, confirmLabel: string, confirmName: string }) =>
+  UIWidget(
+    UIColumn(
+      UIText(o.title).style({ fontSize: 17, fontWeight: 700, color: colors.text, textAlign: "center" }),
+      o.body ? UIText(o.body).style({ fontSize: 14, color: colors.muted, textAlign: "center", lineHeight: "1.4em" }) : null,
+      PrimaryButton("Cancel", { name: "cancel" }),
+    ).style({ bgColor: colors.card, borderRadius: radius.lg, p: spacing.xl, gap: spacing.lg, width: "86%", maxWidth: 360 }),
+  ).style({ top: 0, left: 0, right: 0, bottom: 0, justifyContent: "center", alignItems: "center", overlayColor: colors.scrim })
+```
+
+## Screen rules
+
+- **One file = one screen.** `screens/<id>.ts` default-exports either a value
+  (`export default UIScreen(...).style({...})`) or a function of state (below). Ids are
+  lowercase `[a-z0-9-]`.
+- **Screens are islands.** A screen imports ONLY from `../shared/` — never another screen, no props.
+- **Mock data is the domain.** Realistic inline mock data at the top of the file — the entities and
+  fields ARE the future schema. Real names, real prices, plausible dates, in the product's language
+  (match the user's) — never "Lorem ipsum" or "Item 1". Where a list can be empty, design the empty
+  state too.
+- Give a `name` style (`.style({ name: "submit" })`) to elements that edges refer to — nothing else
+  needs names.
+
+## Screen states (variants)
+
+A screen with more than one look (list vs empty, sheet open, confirm dialog) is ONE file whose
+default export is a function of a state string typed as a string-literal union — the union IS the
+state list, and the parameter default is the canonical state the board shows first. Overlays are
+shown from a state branch, never embedded in the layout:
+
+```ts
+// design/screens/schedule.ts
+import { colors, spacing } from "../shared/tokens"
+import { mainTabs } from "../shared/tabs"
+import { Sheet, PrimaryButton, SectionLabel, ClassCard, EmptyDay } from "../shared/ui"
+
+const classes = [
+  { start: "18:00", end: "19:00", title: "Calisthenics", trainer: "A. Razgulin", price: 800, booked: true },
+  { start: "19:30", end: "21:00", title: "Acrobatics workshop", trainer: "A. Razgulin", price: 1000, seats: 2 },
+]
+
+const FilterSheet = () => Sheet(
+  /* chip groups… */
+  PrimaryButton("Show 1 class", { name: "apply" }),
+)
+
+export default (state: "default" | "empty" | "filters" = "default") => {
+  if (state === "filters") FilterSheet().show()
+  return UIScreen(
+    UIScrollable(
+      SectionLabel("Today"),
+      state === "empty" ? EmptyDay() : UIColumn(classes.map((c) => ClassCard(c, { name: "class" }))).style({ gap: spacing.sm }),
+    ).style({ flexGrow: 1, flexShrink: 1, px: spacing.xl, pt: spacing.md, gap: spacing.lg }),
+    mainTabs.bar("schedule"),
+  ).style({ bgColor: colors.bg, pt: "safe-top" })
+}
+```
+
+Derive per-state data at the top (`const items = state === "empty" ? [] : MOCK`). The board shows a
+state switcher; edges may target `id@state`.
+
+## The map — design_map, never meta.json
+
+`design/meta.json` is the app map: every screen's description/group/role and the edges between
+screens. You READ it from `[File contents]`; you change it ONLY through the `design_map` tool —
+never with a `<file>` write (positions on it are the developer's, and the board may have edited it
+while you were replying). In the same reply that creates screen files, register them:
+
+```
+design_map ops: [
+  { op: "screen", id: "login", desc: "Phone + password sign-in", group: "Onboarding", role: "auth" },
+  { op: "screen", id: "schedule", desc: "Client home — day schedule", role: "list" },
+  { op: "edge", from: "login", to: "schedule", label: "Sign in", activator: "login" },
+  { op: "edge", from: "schedule", to: "schedule@filters", label: "Filters", activator: "filters" }
+]
+```
+
+- New screens get NO position from you — the board auto-places them next to their edge neighbours.
+- **Edges are forward intent only.** Never draw back/dismiss/logout edges (the navigation stack
+  implies returns), and never draw edges between tab screens (the bar already navigates).
+- An edge to the same screen's `id@state` is a *state link* — "tapping X puts this screen into
+  state Y"; the board renders it as a chip on the activator element.
+- **Group every screen** by user-facing area (2–6 per group: Onboarding, Checkout…), **tag its
+  `role`** (`list`, `detail`, `form`, `auth`, `modal`…). Don't regroup existing screens unless asked.
+
+## The tab bar
+
+Declared ONCE in `shared/tabs.ts` — the board discovers it from source and renders it as a rail
+with lanes; tab switching needs NO edges. `defineTabs` is an SDK global: the standard themed
+bottom bar, the same look the built app's `UITabs` renders. The keys are screen ids (each tab's
+root, in tab order), literals only; icons are always `assetIcon(...)` calls:
+
+```ts
+// design/shared/tabs.ts — this declaration is the whole file
+export const mainTabs = defineTabs({
+  schedule: { label: "Schedule", icon: assetIcon("lucide:calendar") },
+  profile:  { label: "Profile",  icon: assetIcon("lucide:user") },
+})
+```
+
+A screen that shows the bar mounts it with a literal tab id — roots AND pushed details that keep
+the bar; a screen that doesn't mount it is a full-screen push. Mount the bar alone when the screen
+owns its layout (`mainTabs.bar("schedule")`, as above) or wrap content with
+`mainTabs.screen("home", [...])`. Restyle through the theme's system keys — `primaryColor`,
+`mutedColor`, `tabbarBg`, `screenBg`, set in `shared/tokens.ts` — never by reimplementing the
+bar. Keep the `defineTabs({...})` declaration and `.screen("<tab>", ...)` / `.bar("<tab>")` call
+shapes intact — the board parses them.
+
+## Icons & fonts
+
+`assetIcon("pack:name")` inlines a registry icon at compile time — the ONLY way to make an icon
+(never hand-write its `{ svg }` result — that renders blank). Use real icons freely on every
+screen. Vendored copies (`design/assets/icons/`, listed under `[Assets]`) resolve first; anything
+else is fetched from the icon registry automatically. The main pack is `lucide` (kebab-case names:
+`"lucide:bell"`, `"lucide:chevron-right"`); an unknown name is a compile error with "did you mean"
+suggestions. Wrap each icon in a tiny factory in `shared/ui.ts`
+(`Icon.bell = (c, s = 20) => UIImage(assetIcon("lucide:bell")).style({ width: s, height: s, tintColor: c })`).
+
+`font("id")` works the same way — registry families load from the font CDN, no vendoring needed:
+`theme({ fontFamily: font("manrope") })`, or per-node `.style({ fontFamily: font("rubik") })`.
+An unknown id or weight is a compile error listing what exists. Only project font files
+(`font("./Brand.ttf")`) must already be pushed.
+
+## spec.md — the concept
+
+The narrative half of the design: the **data model** (entities + fields), the **actors** (who uses
+the app, what each may do), and the **rules & decisions** (validation, edge cases, choices made).
+Prose, co-owned with the developer — edit it with normal `<file>` writes; half-filled is fine. Link
+screens as `[[screen-id]]`. The mock data at the top of each screen is the first draft of the data
+model — promote entities that stabilize into spec.md tables. When you make a design decision worth
+keeping, write it down here instead of leaving it in chat.
+
+## Working style
+
+- Read meta.json, `shared/tokens.ts` and the `shared/ui.ts` signatures before changing anything;
+  open only the screens you need.
+- Design in coherent flows (onboarding → main → detail), not isolated screens; a screen is a
+  moment in a flow. Prefer several focused screens over one mega-screen.
+- The developer watches the board live — your files render as tiles the moment they land, and the
+  selected tile arrives as `[Design]` context: treat it as the subject of an ambiguous instruction.
+- Make it look designed: every value from tokens, one accent doing the talking, realistic content
+  density, empty states designed, press feedback on tappables.