feat: landing-page-design-update

.cursor/rules/design-token-structure.mdc

@@ -0,0 +1,145 @@
+---
+description: Design token and theme file structure for global.css and related theme files. Use when creating, editing, refactoring, or reviewing design tokens, CSS variables, Tailwind theme definitions, primitive palettes, semantic aliases, light and dark theme mappings, or global theme scaffolds. Preserve the canonical section order, standard token naming, and clear grouping for primitive palettes, typography, radius, semantic colours, and theme modes. Treat global.css as the source of truth that overrides base shadcn/ui styling when project tokens exist.
+globs:
+  - "**/global.css"
+  - "**/*theme*.css"
+  - "**/*tokens*.css"
+alwaysApply: false
+---
+
+# Design Token Structure
+
+## Core Principles
+
+- Follow the canonical global theme scaffold and preserve its section order.
+- Keep the file easy to scan, extend, and review.
+- Group related tokens into clear sections with consistent spacing between them.
+- Prefer structure and readability over dense blocks of ungrouped variables.
+- Treat the scaffold as a contract for file structure, not a loose suggestion.
+
+## Relationship to shadcn/ui
+
+- This global.css defines the authoritative design tokens for the application.
+- These tokens intentionally override and extend the default shadcn/ui styling system.
+- Do not rely on default shadcn colour, radius, typography, or surface values when project tokens exist.
+- Always prefer project-defined tokens such as `--color-*`, `--radius-*`, and `--font-*` over library defaults.
+- When adjusting UI styling, modify or extend tokens in global.css rather than hardcoding values in components.
+- Treat shadcn components as primitives that consume this token system, not as the source of design decisions.
+- The design system flows from tokens to components, not from components to tokens.
+
+## Language and Naming Conventions
+
+- Use British English in comments and explanatory prose.
+- Preserve standard ecosystem token naming conventions for variables and aliases.
+- Use `color`, not `colour`, in token and variable names.
+- Use standard Tailwind and CSS token patterns such as `--color-*`, `--font-*`, and `--radius-*`.
+- Do not mix naming styles within the same file.
+
+## Canonical Section Order
+
+Keep files in this order unless there is a strong reason not to:
+
+1. imports and plugins
+2. custom variants
+3. primitive palettes
+4. theme aliases and design tokens
+5. global defaults
+6. light theme (`:root`)
+7. dark theme (`.dark`)
+8. base layer
+
+## Primitive Palettes
+
+- Put raw palette tokens in the primitive palette section.
+- This section may contain neutral palettes, brand palettes, support palettes, or other raw colour families used by the design system.
+- Use consistent palette families such as `--color-<name>-50` through `--color-<name>-950` when appropriate.
+- Keep each palette family together and ordered by scale.
+- Do not scatter primitive palette values across semantic sections.
+- Do not use primitive palette tokens directly in components when semantic tokens exist.
+- Do not assume any specific palette family unless the design system requires it.
+
+## Typography Tokens
+
+- Keep typography tokens together in their own subsection.
+- Leave clear spacing around font declarations so new fonts are easy to add.
+- Separate raw font-family tokens from semantic font aliases where relevant.
+- Avoid duplicating tokens unless the duplication is intentional and documented.
+- Prefer semantic font aliases such as `--font-sans` and `--font-mono` for application use.
+
+## Radius and Primitive Tokens
+
+- Keep radius tokens grouped together in a dedicated subsection.
+- Keep primitive tokens such as base colours, fonts, radius, and shadows separate from semantic aliases.
+- Maintain consistent ordering within each subsection.
+- Extend token scales deliberately rather than ad hoc.
+
+## Semantic Aliases
+
+- Group semantic aliases by domain, for example surface, text, charts, sidebar, or interaction.
+- Keep aliases mapped cleanly to semantic variables such as `--background`, `--primary`, and `--sidebar`.
+- Make semantic alias blocks easy to scan by breaking them into logical subsections.
+- Prefer semantic naming for application usage rather than direct palette references in components.
+
+## Light and Dark Theme Modes
+
+- Keep `:root` for light theme values and `.dark` for dark theme overrides.
+- Preserve the same semantic token order across light and dark sections wherever possible.
+- Keep corresponding light and dark tokens easy to compare.
+- When adding a new semantic token, add it to both light and dark theme sections unless there is a deliberate reason not to.
+- Mirror structure first, then vary values intentionally.
+
+## Formatting and Readability
+
+- Use section comments to break up major areas such as palettes, typography, radius, aliases, and theme modes.
+- Leave deliberate blank lines between major sections and between meaningful subsections.
+- Keep related declarations visually grouped.
+- Avoid long unbroken walls of variables.
+- Optimise for future extension as well as current readability.
+
+## Global Defaults and Base Layer
+
+- Keep non-token global rules such as body letter spacing in a dedicated global defaults section.
+- Keep `@layer base` at the end of the file.
+- Use semantic tokens such as `bg-background` and `text-foreground` in the base layer rather than hardcoded values.
+- Use semantic font aliases such as `var(--font-sans)` in the base layer rather than hardcoded font-family values.
+
+## When Creating a New Token File
+
+- Start from the canonical scaffold rather than generating a token file from scratch.
+- Populate the scaffold while preserving section order and grouping.
+- Define primitive palettes first, then map them into semantic tokens.
+- Keep the scaffold neutral unless the design system clearly requires specific palette families.
+- Do not invent bespoke palette structures unless the project genuinely requires them.
+- Keep the scaffold’s comments and annotations useful for future contributors.
+
+## When Refactoring Existing Files
+
+- Reorganise tokens into the canonical section order.
+- Preserve the existing design intent while improving clarity and grouping.
+- Normalise comments, spacing, and ordering.
+- Remove accidental duplication and flag ambiguous token purpose when necessary.
+- Convert messy or mixed structures into one coherent scaffold.
+
+## Usage in Components
+
+- Components should consume semantic tokens exposed by this file.
+- Do not hardcode colour, radius, typography, or surface values in components when tokens already exist.
+- Do not use primitive palette tokens directly in components unless there is a deliberate low-level reason.
+- Prefer updating the token layer when the design system changes, rather than patching individual components.
+- If shadcn defaults conflict with the project design system, the project token system should win.
+
+## Review Checklist
+
+Before finalising, check that:
+
+- primitive palettes live in one dedicated section
+- typography tokens are grouped with enough space to extend them
+- radius tokens are grouped separately from colours
+- semantic aliases are grouped logically
+- light and dark sections mirror each other clearly
+- comments use British English
+- token names use standard ecosystem spellings such as `color`
+- project tokens override shadcn defaults consistently
+- no hardcoded colours, radius, typography, or surface values remain where tokens exist
+- shadcn components are using semantic tokens rather than raw values
+- the file is easy to scan and extend

.cursor/rules/ui-best-practices.mdc

@@ -0,0 +1,159 @@
+---
+description: UI layout, spacing, alignment, and component styling best practices for consistent, polished interfaces using Tailwind and shadcn/ui. Use when creating or updating UI components, layouts, or styling.
+globs:
+  - "**/*.tsx"
+  - "**/*.jsx"
+  - "**/*.ts"
+  - "**/*.js"
+alwaysApply: false
+---
+
+# UI Best Practices
+
+## Core Principles
+- UI should feel visually balanced, consistent, and intentional.
+- Elements should align cleanly and follow a clear spacing rhythm.
+- Prefer consistency across components over one-off design decisions.
+- Design decisions should scale across the system, not just solve one instance.
+
+---
+
+## Layout and Alignment
+- Align elements to a consistent axis wherever possible.
+- Avoid visual misalignment between adjacent components (icons, buttons, text, dividers).
+- Ensure interactive elements (buttons, inputs, icons) are vertically centred within their containers.
+- Maintain consistent horizontal alignment across sections.
+
+---
+
+## Spacing and Rhythm
+- Use a consistent spacing scale (Tailwind spacing utilities).
+- Ensure padding and margins feel proportional across the UI.
+- Avoid elements touching dividers or edges without intentional spacing.
+- Maintain consistent spacing between:
+  - sections
+  - headings and content
+  - controls and containers
+- Prefer even spacing increments (e.g. 4, 6, 8) over arbitrary values.
+
+---
+
+## Visual Hierarchy
+- Establish a clear hierarchy between:
+  - page titles
+  - section headers
+  - labels
+  - body text
+- Ensure typography scales logically across the UI.
+- Avoid situations where less important elements appear more prominent than primary content.
+- Icons, labels, and controls should feel visually balanced relative to surrounding text.
+
+---
+
+## Icon and Control Consistency
+- Use consistent icon sizes within the same UI context.
+- Ensure icons align visually with text baselines or container centres.
+- Avoid mixing drastically different icon sizes in the same row or toolbar.
+- Maintain consistent sizing for similar controls (buttons, dropdowns, icon buttons).
+
+---
+
+## Borders and Dividers
+- Ensure borders and separators align across sections.
+- Avoid offset or misaligned divider lines.
+- Maintain consistent spacing above and below dividers.
+- Use subtle, consistent border colours (via tokens).
+
+---
+
+## Component Consistency
+- Similar components should share:
+  - sizing
+  - spacing
+  - border radius
+  - interaction behaviour
+- Avoid creating slightly different versions of the same component without reason.
+- Prefer updating shared components over duplicating styles.
+
+---
+
+## Design System Consumption
+- Always consume semantic tokens from `global.css`.
+- Treat `global.css` as the source of truth for colours, typography, radius, and surfaces.
+- Do not hardcode colour, radius, typography, or surface values in component files when tokens exist.
+- If shadcn defaults conflict with project tokens, project tokens win.
+- Prefer Tailwind utility classes that reference tokens (e.g. `bg-background`, `text-foreground`, `border-border`, `ring-ring`).
+- Do not use raw palette values directly in components unless intentionally required.
+
+---
+
+## Component Variant Architecture
+- Shared UI components should define reusable variants rather than one-off styles.
+- Use a variant system such as `class-variance-authority (cva)` for components like:
+  - Button
+  - Badge
+  - Input
+  - Tabs
+  - Card
+- Define variants such as:
+  - `primary`
+  - `secondary`
+  - `outline`
+  - `ghost`
+  - `destructive`
+  - `link`
+- Variants should map to semantic tokens from `global.css`.
+
+### Example expectations
+- `primary` → `bg-primary text-primary-foreground`
+- `secondary` → `bg-secondary text-secondary-foreground`
+- `outline` → `border border-border bg-background`
+- `ghost` → `bg-transparent hover:bg-muted`
+- `destructive` → `bg-destructive text-destructive-foreground`
+
+---
+
+## Component Implementation Rules
+- Component files (e.g. `button.tsx`) should:
+  - define variants
+  - define sizes
+  - define interaction states (hover, focus, disabled)
+  - centralise styling logic
+- Avoid styling components at usage sites when a shared variant should exist.
+- Prefer `asChild` pattern when working with links and buttons.
+
+---
+
+## Interaction States
+- Ensure hover, focus, active, and disabled states are defined consistently.
+- Use token-based colours for states (e.g. `hover:bg-primary/90`).
+- Ensure focus states are accessible and visible (e.g. `focus-visible:ring-ring`).
+
+---
+
+## Accessibility and Feedback
+- Maintain sufficient contrast between text and backgrounds.
+- Ensure interactive elements have clear affordances.
+- Use consistent focus and hover feedback across components.
+
+---
+
+## When Refactoring UI
+- Identify inconsistencies in spacing, alignment, and sizing.
+- Normalise components to follow the shared system.
+- Replace hardcoded values with semantic tokens.
+- Consolidate duplicate patterns into shared components.
+
+---
+
+## Review Checklist
+Before finalising UI changes, check:
+- spacing is consistent and balanced
+- elements are aligned correctly
+- icon sizes are consistent
+- borders and dividers line up
+- typography hierarchy is clear
+- semantic tokens are used instead of hardcoded values
+- shared components are used instead of duplicated styles
+- component variants are defined where needed
+- shadcn components follow the project design system

website/components.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "https://ui.shadcn.com/schema.json",
+  "style": "base-nova",
+  "rsc": false,
+  "tsx": true,
+  "tailwind": {
+    "config": "tailwind.config.ts",
+    "css": "src/styles/global.css",
+    "baseColor": "neutral",
+    "cssVariables": true,
+    "prefix": ""
+  },
+  "iconLibrary": "lucide",
+  "rtl": false,
+  "aliases": {
+    "components": "~/components",
+    "utils": "~/lib/utils",
+    "ui": "~/components/ui",
+    "lib": "~/lib",
+    "hooks": "~/hooks"
+  },
+  "menuColor": "default",
+  "menuAccent": "subtle",
+  "registries": {}
+}

website/package.json

@@ -9,25 +9,30 @@
     "lint": "next lint"
   },
   "dependencies": {
+    "@base-ui/react": "^1.3.0",
     "@docs.page/cli": "workspace:*",
     "@docsearch/js": "^3.6.1",
     "@headlessui/react": "^2.1.8",
     "@mdx-js/mdx": "^3.0.1",
     "@tanstack/react-query": "^5.56.2",
     "@vercel/functions": "^1.4.1",
     "@vercel/og": "^0.6.4",
+    "class-variance-authority": "^0.7.1",
     "classnames": "^2.5.1",
+    "clsx": "^2.1.1",
     "color": "^4.2.3",
     "idb": "^8.0.0",
-    "lucide-react": "^0.445.0",
+    "lucide-react": "0.445.0",
     "mime-db": "^1.53.0",
     "mime-types": "^2.1.35",
     "next": "14.2.13",
     "nprogress": "^0.2.0",
     "react": "18.3.1",
     "react-dom": "18.3.1",
     "react-medium-image-zoom": "^5.2.10",
-    "tailwind-merge": "^2.5.2"
+    "shadcn": "^4.2.0",
+    "tailwind-merge": "^3.5.0",
+    "tw-animate-css": "^1.4.0"
   },
   "devDependencies": {
     "@tailwindcss/typography": "^0.5.15",