---
name: complyform-website
description: >
  Build ComplyForm marketing site pages. Activates when creating or editing Astro
  components, pages, layouts, or styles in the website/ directory. Enforces the
  dark-mode-first design system, performance budget, accessibility baseline, and
  brand aesthetic. Use this skill for any website page creation, component work,
  or styling task.
---

# ComplyForm Website Builder Skill

## Aesthetic Direction

**Restraint is the design.** This is a developer tools site in the tradition of Linear, Resend, and Warp.

- Dark surfaces with layered depth (5-stop grey ramp, not flat black)
- Single teal accent on dark slate — nothing else competes
- Generous whitespace, tight typography, minimal decoration
- Real terminal output as the hero visual — not mockups, illustrations, or stock art
- Copy is sparse and direct. Every word earns its place.

This is NOT a generic SaaS template. Reject: gradient backgrounds, colorful cards, emoji, rounded-everything, "friendly" illustrations, multiple accent colors, floating elements, parallax, particle effects.

## Design Token Contract

All colors MUST come from Tailwind v4 `@theme {}` tokens defined in `src/styles/global.css`. Never use raw hex values in components — always use the auto-generated Tailwind utility classes.

**Tailwind v4 note:** Tokens are defined as `--color-*` variables inside `@theme {}`. Tailwind v4 auto-generates utility classes from these: `--color-page` → `bg-page`, `text-page`; `--color-accent` → `bg-accent`, `text-accent`. There is NO `tailwind.config.mjs` — all config is CSS-first.

| Tailwind Class | `@theme` Variable | Hex | Purpose |
|---|---|---|---|
| `bg-page` | `--color-page` | `#0b0f19` | Page background |
| `bg-surface` | `--color-surface` | `#111827` | Cards, nav, footer |
| `bg-elevated` | `--color-elevated` | `#1e293b` | Code blocks, inputs, pricing rows |
| `border-border` | `--color-border` | `#334155` | Borders, dividers |
| `text-text-muted` | `--color-text-muted` | `#64748b` | Labels, secondary info |
| `text-text-secondary` | `--color-text-secondary` | `#94a3b8` | Body text |
| `text-text-primary` | `--color-text-primary` | `#f1f5f9` | Headings, primary text |
| `text-accent` | `--color-accent` | `#0d9488` | CTAs, links, highlights |
| `bg-accent-hover` | `--color-accent-hover` | `#0f766e` | CTA hover state |

## Typography Rules

- Headings: `font-semibold` (Inter 600). Sizes: h1=`text-4xl md:text-5xl`, h2=`text-3xl`, h3=`text-xl`
- Body: `text-base leading-relaxed` (16px, 1.7 line-height)
- Code: `font-mono text-sm` using stack defined in `@theme { --font-mono: ... }`
- Never go below `text-sm` (14px) for any visible text

## Component Conventions

- All components in `src/components/` as `.astro` files
- Props defined as TypeScript interface at top of component frontmatter
- No default exports — Astro components use named imports
- Interactive components use Astro islands with `client:idle` (not `client:load` unless above the fold)
- Prefer CSS-only solutions over JS. Sticky headers, hover states, and show/hide can all be CSS-only.

## Performance Budget

- **Zero external requests** except Paddle.js CDN and iubenda widget. Everything else self-hosted.
- **No JavaScript frameworks** in islands — vanilla JS or Astro's built-in reactivity only
- Images: use WebP format, include `width` and `height` attributes, use `loading="lazy"` below the fold
- Target: Lighthouse Performance 95+, Accessibility 100

## Accessibility Baseline

- All images: `alt` text (decorative images use `alt=""` with `aria-hidden="true"`)
- All interactive elements: keyboard accessible, visible focus ring (`ring-2 ring-accent ring-offset-2 ring-offset-page`)
- Color contrast: minimum 4.5:1 for body text, 3:1 for large text (>18px bold)
- Skip-to-content link as first focusable element in `Base.astro`
- Semantic HTML: `<nav>`, `<main>`, `<section>`, `<article>`, `<footer>` with appropriate ARIA labels
- `prefers-reduced-motion`: disable all transitions/animations when set

## Responsive Breakpoints

- Mobile-first: base styles are mobile (375px)
- `md:` — tablet (768px): 2-column layouts, expanded nav
- `lg:` — desktop (1024px): full layouts, side-by-side sections
- `xl:` — wide (1440px): max-width container, comfortable reading width
- Container: `max-w-6xl mx-auto px-4 md:px-6 lg:px-8`

## Page Template

Every page in `src/pages/` follows this structure:

```astro
---
import Base from '@layouts/Base.astro';
// page-specific imports
---

<Base title="Page Title — ComplyForm" description="Meta description under 160 chars.">
  <main class="max-w-6xl mx-auto px-4 md:px-6 lg:px-8">
    <!-- page content -->
  </main>
</Base>
```

## SEO Requirements (Every Page)

- Unique `<title>` tag (format: "Page Name — ComplyForm")
- Unique `<meta name="description">` under 160 characters
- OpenGraph: `og:title`, `og:description`, `og:image`, `og:url`, `og:type`
- Canonical URL: `<link rel="canonical" href="https://complyform.dev/page-path">`

## What NOT To Do

1. Never add a light mode or theme toggle
2. Never use colors outside the token system
3. Never add animations beyond subtle hover transitions (opacity, color, transform scale — max 150ms)
4. Never import external CSS frameworks or icon libraries
5. Never use `<img>` without explicit `width`/`height` attributes
6. Never hardcode text that comes from the phase spec — reference the spec
7. Never use `innerHTML` or `dangerouslySetInnerHTML`
8. Never create files outside the `website/` directory
9. Never create `tailwind.config.mjs` — Tailwind v4 is CSS-first via `@theme {}` in `global.css`
10. Never use `@astrojs/tailwind` — deprecated; use `@tailwindcss/vite` Vite plugin
11. Never use `@tailwind base; @tailwind components; @tailwind utilities;` — use `@import "tailwindcss";`
