Skill: Development Workflow

Use when you need to run the project locally, understand the build process, add dependencies, or troubleshoot development issues.

Last verified: February 2026 Maintainer obligation: Update this file when you change the dev server configuration, add new npm scripts, change the Node version requirement, or modify the build pipeline.

Quick Start

cd projects/bfd-style-guide
npm install
npm run dev
# Open http://localhost:4350

Prerequisites

• Node.js 22+ (the GitHub Actions CI uses Node 22; match it locally)
• npm (lockfile is package-lock.json, not yarn or pnpm)

NPM Scripts

Port Configuration

Dev server: port 4350 (fixed, not the Astro default of 4321).

This is set in two places that must stay in sync:

1. astro.config.mjs — server.port: 4350
2. package.json — --port 4350 flags on dev and preview scripts

Why 4350: The monorepo runs multiple Astro projects. 4321 is taken by hsw-site-cms, 4340 by hw-style-guide. 4350 avoids collision.

Build Process

graph LR
    A[npm run build] --> B[Astro collects pages]
    B --> C[Process global.css via Tailwind v4]
    C --> D[Bundle React components via Vite]
    D --> E[Generate static HTML]
    E --> F[dist/ directory]

    F --> G[index.html — the page shell]
    F --> H[_astro/*.css — styles]
    F --> I[_astro/*.js — React bundle]
    F --> J[logos/ favicons]

The build output is entirely static:

• dist/index.html — Single HTML page with Astro island markup
• dist/_astro/ — Hashed CSS and JS bundles
• dist/logos/ — SVG assets

Build time is typically under 2 seconds.

Path Aliases

TypeScript path alias @/* maps to ./src/*:

// tsconfig.json
{
  "compilerOptions": {
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

All component imports use this: import { Navigation } from "@/components/Navigation". This resolves through both Astro's Vite bundler and TypeScript.

Dependencies

Runtime Dependencies

Dev Dependencies

Adding New Content Sections

To add a new brand guidelines section (e.g., "Iconography"):

1. Create src/components/sections/IconographySection/IconographySection.tsx
2. Create src/components/sections/IconographySection/index.ts with the named export
3. Import in src/App.tsx and place it in the <main> stack
4. Add a nav item in src/components/Navigation/Navigation.tsx (navItems array)
5. Give the section a matching id attribute for anchor scrolling

No routing changes needed — this is a single-page app with anchor-based navigation.

Common Issues

"window is not defined" during build

This happens if you change client:only="react" to client:load in index.astro. The React components use browser APIs (window, document, IntersectionObserver) during render. client:only="react" skips server-side rendering entirely. Do not change this.

Tailwind classes not working

If you add a new Tailwind class and it does not apply:

1. Check that the color/token is defined in the @theme {} block in global.css
2. Tailwind v4 auto-generates utilities from @theme tokens. A token --color-bf-foo: #123 automatically creates bg-bf-foo, text-bf-foo, etc.
3. For CSS variables used in var() expressions, they go in the :root {} block, not @theme.

Port already in use

If port 4350 is occupied, check if another instance is running. Kill it rather than changing the port — the port is documented everywhere and changing it creates confusion.

Vite type mismatch in astro.config.mjs

There is a known version mismatch between @tailwindcss/vite and Astro's bundled Vite. The // @ts-ignore on the plugins line in astro.config.mjs suppresses this. The build works correctly — it is purely a type-checking artifact.

Related Skills

• Architecture — Why these technology choices were made
• Deployment — How the build output gets to production
• Components — How the React component tree works