Skip to content

Commit d4921c3

Browse files
matthias-reisclaude
matthias-reis
and
claude
authored
agent(#3): Introduce Next Yak (#5)
* chore(aio): bootstrapping ai work package * docs(plan): Create implementation plan for Next Yak integration - Add comprehensive PLAN.md with detailed scope, architecture, and testing approach - Include rollback strategy and documentation update requirements - Update cost tracking with planning effort metrics 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com> * chore(aio): update task for for implementation * feat(styling): Implement Next Yak integration with Card component - Add next-yak dependency and configure Next.js integration - Create styled Card component with grey border, 1rem padding, and border radius - Replace div containers with Card components on main page (4 total) - Update architecture documentation to reflect Next Yak adoption - Add comprehensive ADR documenting styling engine decision - Include QA checklist for manual testing procedures - Disable Turbopack due to compatibility issues with Next Yak Resolves requirements for styled card display and architecture documentation. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com> * docs: Add pnpm package manager specification - Document pnpm as the official package manager in ARCHITECTURE.md - Update QA checklist to use pnpm commands consistently - Ensure future development adheres to pnpm usage 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com> * fix: cleanups in css area * chore: cleanup issue flow files for #3 --------- Co-authored-by: Claude <noreply@anthropic.com>
1 parent 4ba99d9 commit d4921c3

File tree

9 files changed

+404
-67
lines changed

9 files changed

+404
-67
lines changed

‎docs/ADR/0002-next-yak-adoption.md‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
# ADR 0002: Next Yak Adoption
2+
3+
- **Status**: Accepted
4+
- **Date**: 2025-11-12
5+
- **Deciders**: Core maintainers
6+
- **Related**: Architecture overhaul for styling engine
7+
8+
## Context
9+
10+
The base-component project required a CSS-in-JS styling solution to replace unstyled div containers with properly styled components. The application needed a styling engine that integrates seamlessly with Next.js 16.0.1 and React 19.2.0, while providing a developer-friendly API for creating reusable styled components.
11+
12+
The project's purpose is to showcase a base component called Cask and a theming system with light and dark mode support, requiring a robust styling foundation.
13+
14+
## Decision
15+
16+
We adopted **Next Yak** as the primary styling solution for the following reasons:
17+
18+
- **Next.js Integration**: Next Yak is specifically designed for Next.js with excellent compatibility for versions 16.0.0+
19+
- **Performance**: Build-time CSS extraction provides optimal performance compared to runtime CSS-in-JS solutions
20+
- **Developer Experience**: Familiar styled-components-like syntax reduces learning curve
21+
- **React 19 Compatibility**: Full support for the project's React 19.2.0 requirement
22+
- **TypeScript Support**: First-class TypeScript integration matches the project's tech stack
23+
24+
Alternatives considered and rejected:
25+
- **styled-components**: Runtime CSS-in-JS with potential performance overhead
26+
- **Emotion**: Similar runtime overhead concerns
27+
- **Tailwind CSS**: Would require significant architectural changes and doesn't align with component-focused styling approach
28+
- **CSS Modules**: Lacks the component composition benefits needed for the Cask design system
29+
30+
## Consequences
31+
32+
### Positive outcomes:
33+
- Enables creation of styled Card components with proper encapsulation
34+
- Provides foundation for future theming system implementation
35+
- Improves development experience with styled-components-like API
36+
- Ensures optimal performance through build-time CSS extraction
37+
38+
### Risks and tradeoffs:
39+
- Additional build complexity through next-yak webpack plugin
40+
- Team learning curve for Next Yak specific patterns
41+
- Dependency on Next Yak maintenance and compatibility with future Next.js versions
42+
43+
### Follow-up tasks:
44+
- All new components should use Next Yak for styling consistency
45+
- Future theming system implementation will build on Next Yak foundation
46+
- Component library patterns should be established using Next Yak conventions
47+
48+
## Implementation Notes
49+
50+
- Added `next-yak@8.0.1` to project dependencies
51+
- Updated `next.config.ts` with `withYak()` wrapper for build integration
52+
- Created initial `Card` component as proof-of-concept in `src/components/Card.tsx`
53+
- Replaced four div containers in main page with styled Card components
54+
- Updated architecture documentation to reflect Next Yak as primary styling engine

‎docs/ADR/README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,6 @@ This directory houses the canonical decision log for the project. Follow the [re
55
## Index
66

77
- `0001-record-format.md` — Establishes the required ADR template and submission guidelines.
8-
- `0002-tailwind-v4-migration.md` — Migration from Tailwind CSS v3 to v4 with CSS-first configuration.
8+
- `0002-next-yak-adoption.md` — Adoption of Next Yak as the primary CSS-in-JS styling solution.
99

1010
Add new entries in ascending order with a descriptive filename (e.g., `0002-new-routing-strategy.md`) and update this index accordingly.

‎docs/ARCHITECTURE.md‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,13 @@ This repo is supposed to host a showcase for two features
1616
## Frontend
1717

1818
- Next JS handles basic app bootstrapping and serves only one single page
19-
- Next Yak is the library that we use for styling.
19+
- Next Yak is the CSS-in-JS styling library that provides build-time CSS extraction and styled-components-like API
20+
21+
## Package Management
22+
23+
- **pnpm** is the package manager for this project
24+
- Use `pnpm` commands instead of `npm` for all operations (install, run scripts, etc.)
25+
- The project includes `pnpm-lock.yaml` for dependency locking
2026

2127
## For Agents
2228

‎next.config.ts‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,10 @@
11
import type { NextConfig } from "next";
2+
import { withYak } from "next-yak/withYak";
23

34
const nextConfig: NextConfig = {
45
turbopack: {
5-
root: "."
6-
}
6+
root: __dirname,
7+
},
78
};
89

9-
export default nextConfig;
10+
export default withYak(nextConfig);

‎package.json‎

Lines changed: 9 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -3,30 +3,31 @@
33
"private": true,
44
"scripts": {
55
"aio": "esrun aio/index.ts",
6-
"dev": "next dev -p 4242",
7-
"build": "next build",
6+
"dev": "next dev -p 4242 --webpack",
7+
"build": "next build --webpack",
88
"start": "next start",
99
"lint": "next lint"
1010
},
1111
"engines": {
1212
"node": ">=20"
1313
},
1414
"dependencies": {
15-
"eta": "^3.5.0",
1615
"dotenv": "^16.4.5",
16+
"eta": "^3.5.0",
17+
"next": "16.0.1",
18+
"next-yak": "^8.0.1",
1719
"octokit": "^4.0.0",
18-
"zod": "^3.23.8",
1920
"react": "19.2.0",
2021
"react-dom": "19.2.0",
21-
"next": "16.0.1"
22+
"zod": "^3.23.8"
2223
},
2324
"devDependencies": {
25+
"@biomejs/biome": "2.2.0",
2426
"@types/node": "^20.14.10",
25-
"esrun": "^3.2.28",
26-
"typescript": "^5.5.4",
2727
"@types/react": "^19",
2828
"@types/react-dom": "^19",
29-
"@biomejs/biome": "2.2.0"
29+
"esrun": "^3.2.28",
30+
"typescript": "^5.5.4"
3031
},
3132
"volta": {
3233
"node": "24.11.0"

0 commit comments

Comments
 (0)