fullstorydev/subtext-verify/subtext-recipe-sightmap-setup

Recipe: Sightmap Setup

PREREQUISITE: Read sightmap-authoring (from Subtext) for the full schema reference, and subtext-verify-shared for the sightmap upload step.

Steps

1. Navigate to the page: live-view-navigate(url=...) or live-view-new(url=...)
2. Take a baseline snapshot: live-view-snapshot() to see the current a11y tree with generic roles
3. Identify key UI components in the snapshot (navigation, forms, cards, modals, etc.)
4. Find good selectors using live-view-inspect() — this returns the full component tree with CSS selectors (tag, id, classes, data-* attributes, aria-*, href, etc.) on every node. Use it to identify stable targeting info, then switch back to live-view-snapshot() for normal interaction.

Prefer data-* attributes when available — they're stable and semantically meaningful (e.g., [data-component="ProductTile"], [data-testid="checkout-button"]).

1. Create `.sightmap/components.yaml` with component definitions (see sightmap-authoring for schema)
2. Add memories to key components — contextual notes that appear in a [Guide] section at the top of every snapshot. Focus on:

• Auth/access: passwords, test accounts, login flows (e.g., "Password is 'argus'")
• Stateful components: how toggles, tabs, or modes change the UI (e.g., "Audience toggle switches copy between builder/agent perspectives")
• Forms: required fields, validation rules, expected formats
• Complex interactions: multi-step flows, known quirks, non-obvious behavior

```yaml

• name: LoginForm

selector: "[data-component='LoginForm']" source: src/components/LoginForm.tsx memory:

• "Test account: user@test.com / password123"
• "Shows CAPTCHA after 3 failed attempts"

```

1. Take another snapshot to verify component names appear (definitions are re-read on each snapshot)
2. Add views if the app has distinct routes — specify route patterns and view-scoped components
3. Add requests if key API endpoints should have semantic names — use live-net-list to identify them
4. Verify enrichment: take snapshots on different views, check [View: ...] headers, semantic names, and [Guide] section with memories all appear