Portfolio TDD Workflow

A comprehensive test-driven development skill for building and maintaining a Next.js portfolio project with domain-based architecture, design system patterns, and 100% test coverage.

What This Skill Does

This skill implements a rigorous TDD workflow for a Next.js TypeScript portfolio project owned by Jordy van Vorselen. It enforces architectural patterns, testing standards, and development workflows including:

Instructions

1. Initial Context Setup

When starting any task:

1. Read the repository structure to understand the domain-based architecture

2. Check for related context files in `.claude/` directory:

- `development.md` - Development environment and tooling

- `architecture.md` - System architecture patterns

- `testing.md` - Testing strategies and patterns

- `code-style.md` - Code style guidelines

3. Review workflow files in `.claude/workflows/`:

- `github-issues.md` - Issue tracking workflow

- `tdd-cycle.md` - TDD implementation process

- `commit-standards.md` - Git commit conventions

4. Check relevant guides in `.claude/guides/`:

- `i18n.md` - Internationalization patterns

- `visual-testing.md` - Visual regression testing

- `ci-cd.md` - CI/CD pipeline configuration

2. Architecture Enforcement

**Directory Structure Rules:**

**Component Standards:**

**Icon Usage:**

3. TDD Cycle Implementation

**For Every Feature or Change:**

**RED Phase:**

1. Create a failing test first

2. Test should describe the desired behavior

3. Run `pnpm test` to confirm it fails

4. Commit with prefix: `test: add failing test for [feature]`

**GREEN Phase:**

1. Write minimal code to make the test pass

2. No refactoring, no optimization

3. Run `pnpm test` to confirm it passes

4. Commit with prefix: `feat: implement [feature]` or `fix: [issue]`

**REFACTOR Phase:**

1. Improve code quality without changing behavior

2. Run full test suite after each refactor

3. Commit with prefix: `refactor: [description]`

**Test Coverage Requirements:**

4. Testing Commands

Run tests appropriately based on changes:

```bash

pnpm test # Run all tests

pnpm test:unit # Unit tests only

pnpm test:integration # Integration tests

pnpm test:visual-regression # Visual regression tests

pnpm test:watch # Watch mode for active development

```

**Test File Naming:**

5. Development Workflow

**Before Starting:**

1. Ensure dev server is running: `pnpm dev`

2. Pull latest from main branch

3. Create feature branch following naming convention

4. Review related GitHub issues if applicable

**During Development:**

1. Follow TDD cycle strictly (Red → Green → Refactor)

2. Run linter frequently: `pnpm lint`

3. Format code: `pnpm format`

4. Keep tests passing at all times

5. Commit frequently with conventional commit messages

**Before Pushing:**

1. Run full test suite: `pnpm test`

2. Run build: `pnpm build`

3. Verify no TypeScript errors

4. Ensure all tests pass

5. Review changes for architecture compliance

6. Commit Standards

Follow conventional commit format:

```

<type>(<scope>): <description>

[optional body]

[optional footer]

```

**Types:**

**Examples:**

7. Design System Patterns

**Creating UI Components:**

1. Define component in `src/ui/components/`

2. Use `cva` for variant systems:

```typescript

const variants = cva("base-classes", {

variants: {

size: { sm: "...", md: "...", lg: "..." },

variant: { primary: "...", secondary: "..." }

},

defaultVariants: { size: "md", variant: "primary" }

})

```

3. Export props interface

4. Write comprehensive tests for all variants

5. Add visual regression tests

**Component Composition:**

8. Internationalization (i18n)

When working with user-facing text:

1. Never hardcode strings in components

2. Add translations to appropriate locale files

3. Use translation hook: `const { t } = useTranslation()`

4. Reference keys: `t('namespace.key')`

5. Test all supported locales

9. Quality Checks

Before considering any task complete:

10. Tidy First Methodology

When making changes:

1. **Structural changes first** (refactoring, reorganization)

- Commit: `refactor: restructure [component] for clarity`

2. **Behavioral changes second** (new features, fixes)

- Commit: `feat: add [feature]` or `fix: [issue]`

3. Never mix structural and behavioral changes in one commit

Example Usage

**Adding a New Feature:**

```

1. Read `.claude/workflows/tdd-cycle.md` for TDD process

2. Create failing test: `test: add test for contact form validation`

3. Implement feature: `feat: add contact form with validation`

4. Refactor if needed: `refactor: extract validation logic to utility`

5. Add visual test: `test: add visual regression test for contact form`

6. Run full suite: `pnpm test && pnpm build`

7. Push changes

```

**Fixing a Bug:**

```

1. Create failing test reproducing bug: `test: add failing test for [bug]`

2. Fix the bug: `fix: correct [issue] in [component]`

3. Verify all tests pass

4. Push changes

```

Important Constraints

Quick Command Reference

```bash

Development

pnpm dev # Start dev server (keep running)

pnpm build # Production build

pnpm lint # Run ESLint

pnpm format # Format with Prettier

Testing

pnpm test # All tests

pnpm test:unit # Unit tests only

pnpm test:integration # Integration tests

pnpm test:visual-regression # Visual regression

pnpm test:watch # Watch mode

```