Skip to content

AGENTS.md

Latest commit

 

History

History
66 lines (57 loc) · 3.73 KB

AGENTS.md

File metadata and controls

66 lines (57 loc) · 3.73 KB
Raw

AGENTS.md — agentic flow for this repo

Instructions for agents (and subagents) working in the beautiful-ui-svelte repo (previously scrutiny-design-system) Svelte 5 component library, a port of beautiful-ui (MIT).

When stuck, search the web — don't guess

If a syntax, API, error, or structure isn't landing from memory, or a fix you apply doesn't behave as expected, the answer is very likely not prominent in training data. Before guessing or hacking around it, do a targeted web search:

  • Search the specific symptom / error message verbatim (site:github.com, Stack Overflow, the framework changelog). Someone has usually hit the same error and documented the exact cause.
  • Search for the specific API / syntax (svelte 5 $effect cleanup), not a vague paraphrase.
  • Search for similar problems to learn the real pattern instead of inferring one.
  • Prefer primary sources: official docs, the framework's GitHub issues/PRs, the actual package source.

Guessing at obscure framework behavior wastes more time than the search costs, and breeds subtle bugs that only show up at render time.

Hard-won lessons (elsewhere: LESSONS.md — read it before porting)

  • style:height={viewportH} does NOT append px in Svelte — pass a pre-built string (\${viewportH}px``) or the style is rejected and the layout breaks (ApprovalCard showed all questions stacked).
  • Svelte 5 preserves whitespace inside <pre> (unlike React JSX, which collapses inter-tag whitespace). Inside a <pre>, hug the tags with no indentation between them or literal newlines/indents leak into the code.
  • Svelte STRIPS leading/trailing whitespace inside an element's text content at compile time (the opposite foot-gun of the <pre> one). A trailing space written as {x} inside a tag is REMOVED — words join. React's {x}{" "} idiom becomes Svelte's {x}{' '}; the {' '} expression forces the space into the emitted text node. (Proven at compiler level: <span>{x} </span> → ...${x}</span>; <span>{x}{' '}</span> → ...${x} </span>.) StreamingText showed "Pistachioisyourfastest…" until fixed.
  • GlideHighlight.svelte must bind:this={container} on its root div — without it the hover-glide NEVER renders for any consumer.
  • Svelte-5 runes only (see .agents/skills/svelte-5-runes/SKILL.md). No Svelte-4 export let / $: / <slot> / createEventDispatcher.
  • No $lib alias is configured — use relative imports (../../lib/...).
  • Storybook needs src/app.css — it's imported in .storybook/preview.ts; keep that import or stories render unstyled.
  • Icons are @tabler/icons-svelte (the original's paid set is substituted with closest Tabler equivalents per guidelines.md).
  • Browser-only APIs (ResizeObserver, rAF, window/document listeners, timers) MUST run inside $effect with cleanup — never component top level — for SSR safety.
  • Bare-statement $effect deps compile away — visible; expanded; stage; inside an $effect optimizes to a no-op and the effect never re-fires. Read reactive deps into locals (or into a real if) so Svelte registers them. (ThinkingState's connecting line stayed height: 0px until fixed.)
  • Large components exceed a single write — assemble via a subagent that writes chunked parts and NEVER truncates; then run svelte-check yourself.

Verification loop

  • Fix source, then prove it: render the component in the running Storybook (http://localhost:6006) and inspect the DOM / computed styles with the browser tool, or node ssr-test.mjs <ComponentName> for a fast render-throw check.
  • The SSR/compile check catches ReferenceErrors and render throws; visual fidelity is confirmed against the live story.