UI harness to a healthy agentic front-end development

## Language & technology

- **Primary languages:** TypeScript
- **Runtime versions:** Node.js (no pin — see `package.json` peer deps)
- **Package managers:** yarn
- **Frameworks / load-bearing libs:** Next.js 16.2.6, React 18.2.0, TypeScript 6.0.2, TanStack Form, TanStack Query
- **Linter:** [oxlint](https://oxc.rs/docs/guide/usage/linter)
- **Formatter:** [oxfmt](https://github.com/nicolo-ribaudo/oxfmt)

## Package Scripts

- **Build:** `yarn build:development` / `yarn build:staging` / `yarn build:production`
- **Run (local dev):** `yarn start` (Express + Next.js dev server)
- **Linter:** `yarn lint` (check), `yarn lint --fix` (auto-fix)
- **Formatter:** `yarn fmt:check` (check), `yarn fmt` (auto-format)

## Rules (enforced, not preferences)

These are house rules. If a change violates one, fix the change — don't
relax the rule. Rules live in [`.claude/rules/`](.claude/rules/); add a new
rule by adding a new file and a row here.

- **[COMPONENTS.md](.claude/rules/COMPONENTS.md)** — authoritative map of
  every reusable component and layout in `src/components` and `src/layouts`.
  Read before generating or editing any UI code.
- **[ICONS.md](.claude/rules/ICONS.md)** — icon library reference: all SVG
  icons in `public/svg/icons/`, filename→concept mapping. Always pick from
  this list before creating a new icon.
- **[TOKENS.md](.claude/rules/TOKENS.md)** — authoritative reference for all
  CSS custom properties in `src/styles/tokens.scss`. Use tokens; never
  hardcode color, spacing, or typography values.

## Skills and Slash Commands

| Scaffold a new component or layout    | [`.claude/skills/add-component.md`](.claude/skills/add-component.md)                      |
| Add a new SVG icon                    | [`.claude/skills/add-svg-icon.md`](.claude/skills/add-svg-icon.md)                        |
| Convert a Figma frame to code         | [`.claude/skills/figma-to-code.md`](.claude/skills/figma-to-code.md)                      |
| Give feedback on a finished agent run | [`.claude/skills/give-feedback/SKILL.md`](.claude/skills/give-feedback/SKILL.md)          |
| Set up design-system components       | [`.claude/skills/setup-components/`](.claude/skills/setup-components/)                    |
| Set up / sync CSS design tokens       | [`.claude/skills/setup-css-tokens/`](.claude/skills/setup-css-tokens/)                    |

A set of scripts to validate the environment after tasks

## Verification loop

Run locally before pushing (mirrors CI):

```sh
yarn fmt:check          # oxfmt — formatter check, must be clean
yarn fmt                # oxfmt — auto-format (run before committing)
yarn lint               # oxlint — zero errors required
yarn lint --fix         # oxlint — auto-fix safe violations
yarn build:development  # build sanity check (required in CI)

This one was a friend recommendation and I like the idea. It’s a more narrative way to explain what to do if the agent is stuck on a decision.

## When stuck

- Workspace context: `../CLAUDE.md`
- Org workflow docs: `https://github.com/my-org/ai-workflow/`
- Components guide: [`.claude/rules/COMPONENTS.md`](.claude/rules/COMPONENTS.md)
- Icons guide: [`.claude/rules/ICONS.md`](.claude/rules/ICONS.md)
- Tokens guide: [`.claude/rules/TOKENS.md`](.claude/rules/TOKENS.md)
- Next.js docs: `https://nextjs.org/docs`

# Component & Layout Guide

This document is the authoritative reference for all reusable components and
shared layout primitives. Read it before generating or editing any UI code so
you pick the right building block instead of inventing a new one.

**Scope:**

- `src/components` — atomic, page-agnostic components
- `src/layouts/Shared` — shared layout primitives reused across layouts

**Out of scope (not tracked here):**

- `src/layouts/<OtherLayout>/components/` — layout-private nested components
- `src/layouts/<OtherLayout>/sections/` — layout-specific sections
- Any other sub-folder inside a specific layout

## Quick-reference map

| Need to…                                | Use                |
| --------------------------------------- | ------------------ |
| Show collapsible Q&A items              | `Accordion`        |
| Render a feature/benefit card with icon | `ActionCard`       |
| Bind a form field with TanStack Form    | `InputField`       |

---

## Components (`src/components`)

### Accordion

**File:** `src/components/Accordion/index.tsx`

Collapsible content block built on the native HTML `<details>`/`<summary>`
elements. Uses a compound-component pattern.

  
import Accordion from "@/components/Accordion";

<Accordion name="faq">
{" "}
{/* name groups items so only one opens at a time */}
<Accordion.Summary>Question text</Accordion.Summary>
<Accordion.Content>Answer text or any ReactNode</Accordion.Content>
</Accordion>;
  

**Props — `Accordion`**

| Prop       | Type                  | Required | Description                                            |
| ---------- | --------------------- | -------- | ------------------------------------------------------ |
| `children` | `string \| ReactNode` | yes      | Must include `Summary` and `Content` sub-components    |
| `name`     | `string`              | no       | HTML `name` attribute; groups exclusive-open behaviour |

Sub-components `Accordion.Summary` and `Accordion.Content` accept only
`children: string | ReactNode`.

The `<summary>` automatically renders a `+` / `−` toggle icon — do not add
your own.

# Icon Library

Icons are SVG files located in `public/svg/icons/`. Each file can be
imported and rendered as a JSX element. Use the list below to match a desired
icon concept to the correct filename.

## Available Icons

| File                     | Description / Use case                                        |
| ------------------------ | ------------------------------------------------------------- |
| `arrow-left.svg`         | Back navigation, previous, left direction                     |
| `calculator.svg`         | Calculator, simulator, economy tool                           |
| `hand-shake.svg`         | Handshake , partnership, referral link                        |

## Usage

Import the SVG as a React component (Next.js / SVGR pattern):

import ArrowRight from "@public/svg/icons/arrow-right.svg";

// Render inline
<ArrowRight />;

## Step 1 — Load existing components, styles and design-system context

Look for these rule files. The paths are relative to the project root:

- `.claude/design-system-lib/rules/COMPONENTS.md` — documents available components from the `design-system` library.
- `.claude/design-system-lib/rules/SCSS.md` — documents available SCSS utils from the `design-system` library, like container-queries, functions and reset.
- `.claude/rules/COMPONENTS.md` — documents atomic components already built in this project.
- `.claude/rules/ICONS.md` — documents the icon library in this project.
- `.claude/rules/TOKENS.md` — available atomic CSS tokens on the project.

## Step 2 — Generate the files

Follow the same file set defined in `add-component/skills.md`:

### `src/{resolvedPath}/index.tsx`

- Import types from `./types`.
- Import styles from `./styles.module.scss`.
- Import `Image` from `next/image` only if images are used.
- Build the JSX using the element map from Step 4.
- For links (`<a>`), always add `target="_blank" rel="noopener noreferrer"`.

### `src/{resolvedPath}/styles.module.scss`

- Root class name follows the `camelCase` convention from Step 2.
- All class names are `camelCase`.
- Classes are listed in **alphabetical order**.
- Sub-element classes are named relative to their logical parent (e.g. `.list`, `.listItem`, `.listItemLabel`). Only add nesting when it genuinely reflects a structural relationship.
- Use modern pseudo-selectors where they reduce code: `:not()`, `:has()`, `:is()`, `:where()`, etc.

## Step 3 — Is expected implemented HTML/JSX to follow

- **Semantic HTML** — plain text, headings, links, lists, interactive controls → use native elements (`h1`–`h6`, `p`, `strong`, `em`, `a`, `button`, `ul`, `ol`, `details`, `dialog`, etc.).
- **Container** — a layout wrapper. Use the minimum number of `div` elements; flatten Figma's nested groups whenever the HTML does not need the extra layer.

## Step 4 — Resolve CSS tokens

Open `src/styles/tokens.scss` and read all custom-property names defined there.

For every style value found in Figma (color, spacing, typography, radius, shadow, etc.):

1. **Token exists in `tokens.scss`** → use the CSS custom property: `var(--token-name)`.
2. **Token does NOT exist in `tokens.scss`** → create the token on tokens.scss.
 2.1. New tokens must be grouped by its properties and should be sorted alphabeticaly.
 2.2. New color tokens that use hexadecimal, rgba colors or other color types shoudl be parsed to `oklch`.
 2.3. Do not create tokens for css props like: size, width, height, display or position.

DO NOT wrongly use css tokens on the components, if you don't find then on `tokens.scss` and it is not able to create on `tokens.scss` just put the value and comment. Always double check this.

## Step 5 — Accessibility

- **Interactive elements**: buttons and links must have a discernible accessible name (text content, `aria-label`, or `aria-labelledby`).
- **Images**: every `<Image>` or `<img>` must have a descriptive `alt`. Decorative images get `alt=""` and `aria-hidden="true"`.
- **Semantic structure**: use landmark elements (`<header>`, `<main>`, `<nav>`, `<footer>`, `<section>`, `<article>`) where appropriate instead of generic `<div>`; let the component context inform the right landmark.
- **Heading hierarchy**: do not skip heading levels. If the Figma shows a large title, confirm the correct heading level in context before defaulting to `<h2>`.