DEV Community: Constanza Diaz

How I Built My Design System from a Color Palette (with Claude Code and tweakcn)

Constanza Diaz — Mon, 08 Jun 2026 14:47:23 +0000

Building a coherent and attractive design system is one of those problems that seems simple until you actually sit down to do it. Colors that look great in isolation but clash together, inconsistently named tokens, CSS variables nobody understands three weeks later... This post documents how I solved it by combining Claude Code with tweakcn, a tool I'd never heard of that completely changed my workflow.

The starting point: I had colors, not a system

It all started with a palette. I had my brand colors well defined — primaries, secondaries, neutrals — but the way I'd organized them in code wasn't working for me. I'd set them up directly in Claude Code and, while it functioned, the visual result wasn't what I was after.
The problem wasn't the code itself. It was that I was making design decisions inside a text environment, with no immediate visual feedback. Deciding whether primary-600 should be the hover color or the active color is nearly impossible without seeing it in context.

I got this types of previews from Claude, but I didn't feel it looked good enough, and iterating was not great because I wasn't sure about what I wanted exactly, and it would take up a lot of time and AI tokens...

Discovering tweakcn

While looking for tools to visualize design tokens, I found tweakcn.com/editor/theme. It's a visual theme editor for Tailwind/shadcn that lets you:

Import your existing configuration (CSS variables, Tailwind config)
Edit visually with real-time preview on actual components
Export the result as production-ready code

What makes it particularly useful for developers is that the output isn't just a pretty palette — it's semantic tokens applied to real components. You can immediately see how your destructive color looks on a button, how readable your muted-foreground is as secondary text, or whether the contrast between your card and background is sufficient.

The workflow

Export from Claude Code The first step was getting my existing configuration into a format tweakcn could read. I exported my CSS custom properties as they were:

Import into tweakcn In the tweakcn editor I used the import option to paste my configuration. The editor automatically maps your variables to its semantic token system (background, foreground, primary, secondary, muted, accent, destructive, border, ring...).

Adjust visually This is where the workflow shifts dramatically compared to editing CSS by hand. You can:

Modify the hue, saturation and lightness of each token with sliders
See the change applied in real time across a set of reference components (buttons, cards, inputs, badges, alerts...)
Check foreground/background pairs for readability
Toggle between light and dark mode to make sure both themes are coherent

The adjustments I made were mostly around the lightness values in dark mode — my original setup was too saturated — and fine-tuning the accent color so it had enough contrast with primary without competing with it.

Export the result Once satisfied, tweakcn generates a CSS variables block ready to copy. The output includes both the light and dark themes, with values in HSL format (which makes it trivial to adjust lightness programmatically later if you need to).

Back to Claude Code

With the exported CSS in hand, I went back to Claude Code to integrate it into the project. The process was straightforward: import the variables and let Claude reorganize the token architecture to be consistent with the rest of the codebase.
The result was a complete semantic palette:

What I value most about the final result is that the tokens have semantic meaning, not just color values. The difference between having --color-blue-500 and having --primary is enormous when it comes to maintaining the system: if you rebrand, you change the value of --primary in one place, not forty.

Takeaway: why this workflow works

The Claude Code + tweakcn combination covers two distinct needs:

Claude Code is excellent at generating architecture, naming tokens consistently, and writing CSS boilerplate. But it can't give you visual feedback. tweakcn does exactly that — it puts your colors in context on real components — but it doesn't manage your codebase.
Using them together eliminates the core problem of defining design systems in text: making visual decisions blind.

Resources

tweakcn editor — the theme editor I used
shadcn/ui theming docs — documentation on the token system tweakcn is based on
Claude Code — the terminal agent I used for the codebase

Do you have a different approach to managing design tokens? I'd love to know what tools you use — drop it in the comments.

Multilanguage good practices.

Constanza Diaz — Mon, 08 Jun 2026 14:11:13 +0000

My i18n Setup Was Right. Until It Wasn't.

Best practices have an expiry date. They expire silently.

I'm building a 4-language landing page for a client — Catalan, Spanish,
English, French. Before I wrote a single page, I asked Claude what the
cleanest way to do i18n in Astro was. The answer was solid. I wrote it into
the specs. The scaffold worked.

Until I added a second page. This is the story of how I almost shipped a
maintenance nightmare without ever breaking a single rule from my own
specs.

The setup

The original recommendation was straightforward: one file per language.
Astro had recently stabilized native i18n support — the i18n: {
defaultLocale, locales, routing } block in astro.config.mjs — and the
simplest pattern paired that config with a directory tree like:

src/pages/
├── index.astro # Catalan (default)
├── es/index.astro # Spanish
├── en/index.astro # English
└── fr/index.astro # French

Four files. One per language. Each file pulled its strings from a shared
src/i18n/ui.ts catalogue, so the content was DRY even if the structure
wasn't. This worked. It went into the specs as the canonical pattern.

The growth

Months in, the project needed two more pages: /gallery and /press. I did
what any disciplined builder does — I followed the existing pattern. Two
new pages. Eight new files.

Something started to feel off, but I couldn't name it. The specs said "one
file per language." I was following the specs.

The catch

It clicked during a review with Claude. I asked, almost as a sanity check:
"we made four versions with the text hardcoded in each language?" — and as
I typed the question, I heard how absurd it sounded.

We had four copies of every page. The structure was duplicated. The text
was duplicated. Every bug would be quadrupled. And worse: when a file lives
in an es/ folder, the brain treats it as "the Spanish version" — so you
start writing Spanish strings directly into the file, bypassing the very
i18n catalogue you built. The pattern itself was inviting the regression.

That was the symptom. The cause was deeper: the per-language file pattern
scales the wrong axis. Add a new page and your surface multiplies by N
(where N is the number of languages). The structure and the language are no
longer orthogonal.

The refactor

Astro has a feature the original setup hadn't been using: dynamic routes
via [lang]. One file generates a route for each parameter, statically, at
build time:

src/pages/
├── index.astro # / (Catalan, default)
├── gallery.astro # /gallery (Catalan)
├── press.astro # /press (Catalan)
└── [lang]/
├── index.astro # /es, /en, /fr
├── gallery.astro # /es/gallery, /en/gallery, /fr/gallery
└── press.astro # /es/press, /en/press, /fr/press

Six files instead of thirteen. A 54% reduction in surface area. The
structure lives in one place per page. The language varies via the route
param. The catalogue handles the strings. Each axis is finally orthogonal.

The refactor itself took about an hour: getStaticPaths per file, swap
useTranslations('es') for useTranslations(Astro.params.lang), rewrite the
language switcher to do a URL-prefix swap.

Why this matters

I wasn't violating my specs. The specs were the trap. They encoded the
assumption that the project would stay at one or two pages — an assumption
that was true when I wrote them, and stopped being true the moment I added
the third.

Specs are snapshots. They capture what you knew when you wrote them. A spec
that says "follow pattern X" is silently dependent on the conditions that
made X a good idea in the first place. When those conditions change, the
rewrite the language switcher to do a URL-prefix swap.

Why this matters

I wasn't violating my specs. The specs were the trap. They encoded the assumption that the project would stay at one or two pages — an
assumption that was true when I wrote them, and stopped being true the moment I added the third.

Specs are snapshots. They capture what you knew when you wrote them. A spec that says "follow pattern X" is silently dependent on the
conditions that made X a good idea in the first place. When those conditions change, the spec stops protecting you and starts pushing
you toward the wrong answer.

The takeaway isn't "review your specs every time you add a feature." That's exhausting and nobody does it. The takeaway is to listen to
friction. When you find yourself hardcoding strings, or copy-pasting structure, or saying "this is the third time I'm doing this" —
that's the signal that a pattern is past its expiry date.

Takeaway

Best practices have an expiry date. They expire silently.

The agent writes the code, the spec sets the pattern, but you're still the engineer. The friction in your hands is the only thing that
knows when something used to be right and isn't anymore.

AI Pair Programming Isn't Autopilot: Scaffolding HandyFEM and Catching What the AI Threw Away

Constanza Diaz — Mon, 01 Jun 2026 20:26:20 +0000

The agent writes the code. You're still the engineer.

I'm building HandyFEM with Claude Code as my pair. It's fast — sometimes startlingly so. But the way I work with it is deliberate: I treat everything it produces the way I'd treat a pull request from a capable junior developer. I read it. I question it. I decide what stays.

This post is a concrete example of why that habit matters.

The task: scaffolding the project

Before writing features, you scaffold a project — generate its skeleton: folder structure, config files, a base page that runs. I had the agent set up the foundation for HandyFEM:

Next.js with TypeScript and Tailwind
shadcn/ui — component code lives in your repo, so you own it
Design tokens wired into the theme — exact color palette from my specs

Because my project folder already had docs, Git, and a .env.local with a real secret, the agent did the smart thing: generated the app in a temporary folder and integrated carefully, without clobbering my existing files.

The catch

During the integration, the agent mentioned — almost in passing — that the Next.js generator had created its own CLAUDE.md file, and that it had discarded it so as not to overwrite mine.

On the surface: correct behavior. But it raised a question I didn't want to skip. Did that discarded file contain anything useful?

So I asked. We went back and looked. The generated CLAUDE.md pointed to a second file — AGENTS.md — and that one held something genuinely valuable:

# This is NOT the Next.js you know

This version has breaking changes — APIs, conventions, and file structure may
all differ from your training data. Read the relevant guide in
node_modules/next/dist/docs/ before writing any code.

Real. The framework version I'm using is newer than most AI models were trained on. Losing this note meant the agent might later write code using outdated patterns — confidently, and wrongly.

We rescued it into my project instructions. One small note, but it changes the quality of every future line of framework code.

Why this matters

The agent didn't do anything wrong. Discarding a file to protect mine was sensible. But the side effect — dropping context that mattered — was easy to miss, buried in a one-line aside during a much bigger operation.

That's the pattern to internalize. AI agents make a high volume of fast, plausible decisions. Most are good. But "plausible" isn't "reviewed." The skill isn't prompting — it's reading the output like a reviewer: what did it change, what did it remove, is each of those what I actually want?

I don't review because the tool is bad. I review because it's good enough that I'd otherwise stop paying attention. That's the trap.

Honest reflections on the workflow

What's working:

Security before features. Pre-commit hook, .gitignore, environment variables — all set up before scaffolding. For a product whose whole premise is trust, that ordering is non-negotiable.
Detailed specs as source of truth. The agent had real screens, components, and a color palette to build against — not an invitation to invent one.
CLAUDE.md with project conventions. Mobile-first, accessibility minimums, never hardcode secrets. The agent defaults to my standards instead of generic ones.

What I'd refine:

Decide manual vs. automated before committing to a path. Earlier I had the agent script a one-time setup task. It became a long debugging session. Doing it by hand would have been faster. Automation pays off when you repeat something — for a true one-off, manual is often smarter.
Take inventory before opening a new thread. Some questions I treated as open were already answered in my own specs. Five minutes of review saves re-litigating settled decisions.

The meta-lesson: with an AI agent, the bottleneck shifts. It's no longer writing the code — it's deciding well and reviewing carefully. The typing got cheap. The judgment got more valuable, not less.

Takeaway

An AI agent is a genuine force multiplier — but only for someone who stays in the driver's seat. It will move faster than you, make mostly-good calls, and occasionally drop something that matters in a sentence you could easily skim past.

So don't skim. Read the diff. Ask "what did you remove, and why?"

The agent writes the code. You're still the engineer.

#HandyFEMApp #BuildingInPublic #AI #ClaudeCode #WebDev

Security by Design: Keeping API Tokens Out of Git with a 3-Layer Setup

Constanza Diaz — Mon, 01 Jun 2026 20:17:26 +0000

When you build a product whose entire reason to exist is safety, security can't be something you bolt on later. It has to be a default — baked into the workflow from day one.

So before any application code, I set up how my app handles secrets. This post walks through that setup: a deliberate, three-layer approach that makes it structurally impossible for a token to end up in version control.

The star of the show is a Git pre-commit hook. I'll explain it from scratch.

Defense in depth

No single control should be the only thing standing between you and a leak. Three layers, each catching what the previous one might miss:

.gitignore — prevention: keep secret-bearing files out of Git entirely
A pre-commit hook — detection: scan every commit for secrets and block it if one slips through
Environment variables — design: keep secrets out of the codebase in the first place

Layer 1 — `.gitignore`

# Environment variables
.env
.env.*
!.env.example

The !.env.example exception keeps a template in the repo — a documented list of which variables are needed, with empty values. Anyone picking up the project knows exactly what to fill in without ever seeing a secret.

Layer 2 — the `pre-commit` hook

A Git hook is a script Git runs automatically at a specific moment. A pre-commit hook runs right before a commit is created:

git commit
    │
    ▼
pre-commit hook runs   ← automatic
    │
    ├─ secret found?  → ❌ commit blocked
    └─ all clean?     → ✅ commit proceeds

Mine scans staged files for patterns that match real credentials — Atlassian tokens, AWS keys, private keys. If it finds one, the commit is blocked:

#!/usr/bin/env bash
set -euo pipefail

files=$(git diff --cached --name-only --diff-filter=ACM)
[ -z "$files" ] && exit 0

patterns='ATATT[A-Za-z0-9_=-]{16,}|AKIA[0-9A-Z]{16}|gh[pousr]_[A-Za-z0-9]{20,}|-----BEGIN [A-Z ]*PRIVATE KEY-----'

found=0
while IFS= read -r f; do
  [ -n "$f" ] || continue
  content=$(git show ":$f" 2>/dev/null || true)
  if printf '%s' "$content" | grep -nEq "$patterns"; then
    echo "❌ Possible secret in: $f"
    found=1
  fi
done <<< "$files"

if [ "$found" -ne 0 ]; then
  echo "🛑 Commit blocked: secrets detected in staged files."
  exit 1
fi

Two things worth knowing:

The exit code is everything. If a pre-commit hook exits non-zero, Git aborts the commit. That single exit 1 is what makes this real.

I keep the hook in the repo. Git's default hooks live in .git/hooks/, which isn't versioned. I store mine in a tracked .githooks/ folder and point Git at it:

git config core.hooksPath .githooks

Now the hook travels with the project and gets reviewed like any other code.

Layer 3 — environment variables

The first two layers stop secrets from being committed. The third makes sure they're not in the code to begin with:

const CONFIG = {
  apiToken: process.env.JIRA_API_TOKEN,
}

if (!CONFIG.apiToken) {
  console.error("Missing JIRA_API_TOKEN. Run with: node --env-file=.env.local script.js")
  process.exit(1)
}

On Node 20.6+, no dotenv dependency needed — the built-in --env-file flag loads your .env.local:

node --env-file=.env.local script.js

Testing it

The best way to trust a safety net is to test it:

echo 'const token = "ATATT3xFAKEFAKEFAKEFAKEFAKE123456"' > leak-test.js
git add leak-test.js
git commit -m "test"
# ❌ Possible secret in: leak-test.js
# 🛑 Commit blocked: secrets detected in staged files.

The commit never happens. That's the point.

Takeaway

Security works best when the tooling enforces the rules — not your memory. Three small pieces of configuration and a whole category of mistakes simply can't happen.

For HandyFEM, where trust is the product, this wasn't over-engineering. It was the starting line.

📚 HandyFEM App Series
🔗 Previous: From Specs to Tickets: Automating Jira Setup with Node.js
🔗 Next: Coming soon — Building the Design System in Code with Claude Code

🏷️ All posts in this series: #HandyFEMApp

*Follow the build: #HandyFEMApp *

Security by Design: Keeping API Tokens Out of Git with a 3-Layer Setup

Constanza Diaz — Mon, 01 Jun 2026 14:47:33 +0000

When you build a product whose entire reason to exist is safety, security can't be something you bolt on later. It has to be a default — baked into the workflow from day one.

The star of the show is a Git pre-commit hook. I'll explain it from scratch.

Defense in depth

No single control should be the only thing standing between you and a leak. Three layers, each catching what the previous one might miss:

.gitignore — prevention: keep secret-bearing files out of Git entirely
A pre-commit hook — detection: scan every commit for secrets and block it if one slips through
Environment variables — design: keep secrets out of the codebase in the first place

Layer 1 — `.gitignore`

# Environment variables
.env
.env.*
!.env.example

Layer 2 — the `pre-commit` hook

A Git hook is a script Git runs automatically at a specific moment. A pre-commit hook runs right before a commit is created:

git commit
    │
    ▼
pre-commit hook runs   ← automatic
    │
    ├─ secret found?  → ❌ commit blocked
    └─ all clean?     → ✅ commit proceeds

Mine scans staged files for patterns that match real credentials — Atlassian tokens, AWS keys, private keys. If it finds one, the commit is blocked:

#!/usr/bin/env bash
set -euo pipefail

files=$(git diff --cached --name-only --diff-filter=ACM)
[ -z "$files" ] && exit 0

patterns='ATATT[A-Za-z0-9_=-]{16,}|AKIA[0-9A-Z]{16}|gh[pousr]_[A-Za-z0-9]{20,}|-----BEGIN [A-Z ]*PRIVATE KEY-----'

found=0
while IFS= read -r f; do
  [ -n "$f" ] || continue
  content=$(git show ":$f" 2>/dev/null || true)
  if printf '%s' "$content" | grep -nEq "$patterns"; then
    echo "❌ Possible secret in: $f"
    found=1
  fi
done <<< "$files"

if [ "$found" -ne 0 ]; then
  echo "🛑 Commit blocked: secrets detected in staged files."
  exit 1
fi

Two things worth knowing:

The exit code is everything. If a pre-commit hook exits non-zero, Git aborts the commit. That single exit 1 is what makes this real.

I keep the hook in the repo. Git's default hooks live in .git/hooks/, which isn't versioned. I store mine in a tracked .githooks/ folder and point Git at it:

git config core.hooksPath .githooks

Now the hook travels with the project and gets reviewed like any other code.

Layer 3 — environment variables

The first two layers stop secrets from being committed. The third makes sure they're not in the code to begin with:

const CONFIG = {
  apiToken: process.env.JIRA_API_TOKEN,
}

if (!CONFIG.apiToken) {
  console.error("Missing JIRA_API_TOKEN. Run with: node --env-file=.env.local script.js")
  process.exit(1)
}

On Node 20.6+, no dotenv dependency needed — the built-in --env-file flag loads your .env.local:

node --env-file=.env.local script.js

Testing it

The best way to trust a safety net is to test it:

echo 'const token = "ATATT3xFAKEFAKEFAKEFAKEFAKE123456"' > leak-test.js
git add leak-test.js
git commit -m "test"
# ❌ Possible secret in: leak-test.js
# 🛑 Commit blocked: secrets detected in staged files.

The commit never happens. That's the point.

Takeaway

Security works best when the tooling enforces the rules — not your memory. Three small pieces of configuration and a whole category of mistakes simply can't happen.

For HandyFEM, where trust is the product, this wasn't over-engineering. It was the starting line.

📚 HandyFEM App Series
🔗 Previous: From Specs to Tickets: Automating Jira Setup with Node.js
🔗 Next: Coming soon — Building the Design System in Code with Claude Code

🏷️ All posts in this series: #HandyFEMApp

*Follow the build: #HandyFEMApp *

Security by Design: Keeping API Tokens Out of Git with a 3-Layer Setup

Constanza Diaz — Mon, 01 Jun 2026 14:47:33 +0000

When you build a product whose entire reason to exist is safety, security can't be something you bolt on later. It has to be a default — baked into the workflow from day one.

The star of the show is a Git pre-commit hook. I'll explain it from scratch.

Defense in depth

No single control should be the only thing standing between you and a leak. Three layers, each catching what the previous one might miss:

.gitignore — prevention: keep secret-bearing files out of Git entirely
A pre-commit hook — detection: scan every commit for secrets and block it if one slips through
Environment variables — design: keep secrets out of the codebase in the first place

Layer 1 — `.gitignore`

# Environment variables
.env
.env.*
!.env.example

Layer 2 — the `pre-commit` hook

A Git hook is a script Git runs automatically at a specific moment. A pre-commit hook runs right before a commit is created:

git commit
    │
    ▼
pre-commit hook runs   ← automatic
    │
    ├─ secret found?  → ❌ commit blocked
    └─ all clean?     → ✅ commit proceeds

Mine scans staged files for patterns that match real credentials — Atlassian tokens, AWS keys, private keys. If it finds one, the commit is blocked:

#!/usr/bin/env bash
set -euo pipefail

files=$(git diff --cached --name-only --diff-filter=ACM)
[ -z "$files" ] && exit 0

patterns='ATATT[A-Za-z0-9_=-]{16,}|AKIA[0-9A-Z]{16}|gh[pousr]_[A-Za-z0-9]{20,}|-----BEGIN [A-Z ]*PRIVATE KEY-----'

found=0
while IFS= read -r f; do
  [ -n "$f" ] || continue
  content=$(git show ":$f" 2>/dev/null || true)
  if printf '%s' "$content" | grep -nEq "$patterns"; then
    echo "❌ Possible secret in: $f"
    found=1
  fi
done <<< "$files"

if [ "$found" -ne 0 ]; then
  echo "🛑 Commit blocked: secrets detected in staged files."
  exit 1
fi

Two things worth knowing:

The exit code is everything. If a pre-commit hook exits non-zero, Git aborts the commit. That single exit 1 is what makes this real.

I keep the hook in the repo. Git's default hooks live in .git/hooks/, which isn't versioned. I store mine in a tracked .githooks/ folder and point Git at it:

git config core.hooksPath .githooks

Now the hook travels with the project and gets reviewed like any other code.

Layer 3 — environment variables

The first two layers stop secrets from being committed. The third makes sure they're not in the code to begin with:

const CONFIG = {
  apiToken: process.env.JIRA_API_TOKEN,
}

if (!CONFIG.apiToken) {
  console.error("Missing JIRA_API_TOKEN. Run with: node --env-file=.env.local script.js")
  process.exit(1)
}

On Node 20.6+, no dotenv dependency needed — the built-in --env-file flag loads your .env.local:

node --env-file=.env.local script.js

Testing it

The best way to trust a safety net is to test it:

echo 'const token = "ATATT3xFAKEFAKEFAKEFAKEFAKE123456"' > leak-test.js
git add leak-test.js
git commit -m "test"
# ❌ Possible secret in: leak-test.js
# 🛑 Commit blocked: secrets detected in staged files.

The commit never happens. That's the point.

Takeaway

Security works best when the tooling enforces the rules — not your memory. Three small pieces of configuration and a whole category of mistakes simply can't happen.

For HandyFEM, where trust is the product, this wasn't over-engineering. It was the starting line.

📚 HandyFEM App Series

🔗 Previous: From Specs to Tickets: Automating Jira Setup with Node.js and the Jira API

🔗 Next: none (latest post)

🏷️ All posts in this series: #HandyFEMApp

*Follow the build: #HandyFEMApp *

From Specs to Tickets: Automating Jira Setup with Node.js and the Jira API

Constanza Diaz — Sun, 31 May 2026 15:19:38 +0000

The plan was simple

Take the specs we'd written, turn them into Jira epics, stories and subtasks, and start sprinting.

It took longer than expected. Here's what actually happened — and what I learned.

Why automate Jira setup at all?

HandyFEM has 8 epics, 37 stories and ~160 subtasks. Creating that manually would take a full day and be error-prone. More importantly: the specs were already written in a structured format. Translating structured data into Jira issues is exactly the kind of repetitive task that should be automated.

So I wrote a Node.js script to do it via the Jira REST API.

Problem 1 — Jira Spaces ≠ Jira Classic

My account uses Jira Spaces — Atlassian's newer interface. The classic Jira has CSV import built in. Jira Spaces doesn't.

This isn't documented anywhere obviously. You discover it by looking for the import option and not finding it.

Lesson: always check which version of Jira you have before planning your workflow. The API still works, but some endpoints behave differently.

Problem 2 — The API token wasn't the issue (until it was)

First attempt: connection error. I assumed it was the token. It wasn't — it was an expired token from a previous session. Regenerating it fixed the connection.

The real lesson: curl -u email:token https://your-domain.atlassian.net/rest/api/3/myself is the fastest way to verify auth before running any script.

Problem 3 — `customfield_10014` doesn't exist in team-managed projects

In classic Jira, linking a story to an epic uses a field called customfield_10014 (Epic Link). In team-managed projects (Jira Spaces), this field doesn't exist. You use parent instead.

The error was clear once I saw it:

"customfield_10014": "Field cannot be set. It is not on the appropriate screen, or unknown."

Fix: remove customfield_10014, keep only parent: { id: epicId }.

Problem 4 — Board search doesn't work for team-managed projects

The Agile API endpoint /rest/agile/1.0/board?projectKeyOrId=HFM returns empty for team-managed projects, even when the board exists.

Claude Code caught this one after the first failure — it explained the root cause and the fix: hardcode the board ID directly instead of searching for it.

// This doesn't work for team-managed projects:
const boards = await fetch(`/rest/agile/1.0/board?projectKeyOrId=HFM`)

// This does:
const board = { id: 1, name: "SCRUM board" }

What the final setup looks like

8 epics covering the full project lifecycle:

Planning & architecture (done)
Design System (in progress)
MVP screens (in progress)
Backend / Supabase
Security & privacy
PWA + SEO + emails
Testing & launch
AI Agentic features (v2)

37 stories with detailed descriptions and acceptance criteria.

~160 subtasks per story — including one for writing the blog post before closing the story. That last one matters: documentation that lives next to the work gets written. Documentation planned separately doesn't.

8 sprints mapped to the logical build order — from DS implementation to public launch in Barcelona.

Security: never hardcode tokens

The scripts use node --env-file=.env.local (native in Node v18+) to load credentials. No dotenv dependency, no token in the codebase.

node --env-file=.env.local docs/handyfem-jira-import.js

Both scripts are in .gitignore. Claude Code was instructed to never write sensitive values directly — always give instructions for the developer to add them manually.

What I'd do differently

Start with a simple API test before writing the full script. One curl call to verify auth and one to verify the project endpoint would have saved 30 minutes of debugging, and a lot of Claude tokens.

Also: when automating Jira, always check whether your project is classic or team-managed first. The API surface is different enough to matter.

The scripts

Both scripts are in docs/ in the HandyFEM repo:

handyfem-jira-import.js — creates epics, stories and subtasks
handyfem-jira-sprints.js — creates sprints and assigns issues

📚 HandyFEM App Series

🔗 Previous: Building HandyFEM’s Design System with Claude.ai: Specs, Components, and Visual Previews

🔗 Next: Security by Design: Keeping API Tokens out of Git with a 3-Layer Setup

🏷️ All posts in this series: #HandyFEMApp

Building in public. All mistakes included.

Building HandyFEM's Design System with Claude.ai — Specs, Components and Visual Previews

Constanza Diaz — Sun, 31 May 2026 12:35:03 +0000

What is a Design System and why build it first?

A Design System is a single source of truth for all visual and interaction decisions in an app — colors, typography, spacing, components, states, accessibility rules.

The reason to build it before any screen is simple: if you change the primary color after building 7 screens, you're updating it in 40 places. If you change it in the DS, it propagates everywhere automatically.

For HandyFEM I built the DS in two layers:

Layer 1 — Tokens: CSS variables and Tailwind config values. Colors, spacing, border radius, shadows, transitions. Everything that gets used across components.

Layer 2 — Components: Button, Input, Card, Badge, Avatar. Each one with all variants, all states, and full accessibility spec.

The token decisions: here are some design desicions.

Colors

The palette was already defined from HandyFEM's social media posts and brand materials — teal as primary, violet as accent, with neutrals for backgrounds and borders.

The key decision was dropping the cream background in favor of clean white and light gray. Cream looks warm in isolation but gets muddy next to colored components. White/gray lets the teal and violet breathe.

--color-primary: #4A7C7D;      /* teal */
--color-accent: #776AAA;       /* violet */
--color-bg-primary: #ffffff;
--color-bg-secondary: #F5F5F5;
--color-border: #E0DDD6;       /* neutral gray */
--color-amber: #FCC970;        /* ratings only */

Spacing

Base 4px system. Every spacing value is a multiple of 4. This sounds rigid but in practice it makes layouts feel consistent without effort.

Border radius

The interesting decision here: buttons are 8px (rounded), not pill-shaped. The navbar is pill (9999px). This combination — pill navbar + rounded buttons — is what Linear, Vercel and Notion use. It gives sophistication without being generic.

The components

DS-01 — Button

Four variants: primary (teal), secondary (violet outline), ghost (text only), destructive (red outline). Three sizes: large (48px), medium (40px), small (32px for filters and chips).

The non-obvious decisions:

Loading state blocks double-submit — critical for auth forms
Destructive always requires an AlertDialog confirmation before firing
@media (hover: hover) wrapping on all hover effects — no sticky hover states on touch devices
prefers-reduced-motion removes scale animation, keeps color changes

DS-02 — Inputs

Label always above, never floating. Floating labels are visually clever but have serious accessibility edge cases with screen readers and mobile keyboards. Not worth it.

Validation fires onBlur — never in real time while typing. Real-time validation is annoying when you haven't finished the word yet.

The file upload component has drag-and-drop, immediate preview, and opens camera/gallery on mobile. This matters for the professional onboarding — portfolio photos are a core part of the profile.

DS-03 — Professional Cards

Two layouts: horizontal for mobile (photo left, info right), vertical for desktop (photo top, info bottom in a 2-column grid). The border is 0.5px solid #E0DDD6 — neutral gray, not the lavender that was in the first iteration. The lavender competed with the content. Gray doesn't.

The "Verified" badge has a pulsing green dot. Small detail, big signal — it communicates that the profile is active and has been reviewed.

DS-04 — Badges and Chips

Status badges are pill-shaped. Category tags are rounded (6px). This distinction encodes hierarchy — pill for important single states, rounded for informational groups. Same pattern that GitHub and Linear use.

Filter chips show an X icon when active. One pending polish note: the X is too small and slightly misaligned — will fix in code, not in spec.

DS-05 — Avatar

Color assigned by name, not randomly. The first character of the name maps to one of four background colors via charCode % 4. Marta López is always lavender. Sara Ruiz is always teal. Consistent across the whole app, across all devices, forever.

The workflow: spec → visual preview → approve → document

For each component, the process was:

Define variants, states, and decisions in text
Generate a live visual preview in Claude Design
Review and adjust (border color, shape, sizing)
Lock the decision in docs/handyfem-specs.md

Having the visual preview before writing code meant design decisions were made consciously, not discovered mid-implementation. The spec document in /docs is now the reference for every component — Claude Code will use it to generate the actual React + Tailwind + shadcn/ui code.

What the spec document looks like

Each component entry in handyfem-specs.md includes:

All variants with exact hex values
All states (default, hover, focus, error, disabled, loading)
Token references (no hardcoded values)
Accessibility requirements (aria attributes, focus rings, touch targets)
shadcn/ui implementation notes
Props interface

This is specs-driven development — write the spec, then write the code. A well-written spec is also the prompt for Claude Code, which means the first generated output is much closer to final.

The interaction details

Four effects, chosen carefully:

Navbar pill with scroll shrink — uses animation-timeline: scroll() to progressively shrink the navbar from 100% to 88% as the user scrolls. Degrades gracefully on Firefox (stays at 100%, still functional).

Hero fade + slide up — opacity: 0 → 1 with translateY(16px → 0) on load. Staggered: title first, subtitle 100ms later, CTAs 200ms later.

Card hover — translateY(-2px) with a teal-tinted shadow. Only on @media (hover: hover) — touch devices don't get stuck hover states.

Scroll-triggered fade — sections enter the viewport with a fade + slide via IntersectionObserver. Implemented as a reusable useScrollReveal hook.

All four respect prefers-reduced-motion.

What's next

The Design System spec is done. Next step: Claude Code — implementing all of this as actual React components in the Next.js project, starting with globals.css, tailwind.config.ts, and the component files one by one.

After that: building the 7 MVP screens using the DS as the foundation.

But first. Let's make a proper plan, by using JIRA to organize all the work!

📚 HandyFEM App Series

🔗 Previous: From Idea to Specs: Planning HandyFEM's Architecture with Claude.ai - Specs Driven Development

🔗 Next: From Specs to Tickets: Automating Jira Setup with Node.js and the Jira API

Building in public. All mistakes included.

From Idea to Specs: Planning HandyFEM's Architecture with Claude.ai - Specs Driven development.

Constanza Diaz — Fri, 29 May 2026 15:03:05 +0000

What is HandyFEM?

HandyFEM is a web app I'm building to connect women professionals in technical trades (electricians, plumbers, carpenters...) with clients who are looking for them. It's both a real product I plan to launch and a portfolio project — so it has to be well-built, secure, and professional.
I'm documenting the entire process as I go. This is the first post in the series.

The problem with jumping straight into code

Without a solid plan, we can find several problems, features that don't connect, components that have to be rebuilt, a design that makes sense locally but not globally.
So I decided to do it properly — specs first, code second.
I used Claude.ai as a thinking partner throughout this process. Not just to generate content, but to challenge my decisions, suggest alternatives, and help me document everything in a structured way.

Step 1 — Reviewing the user flow

I already had a flow diagram from a previous iteration of the project. We started there. I put my diagram to be judged by Claude and it identified a few issues or things that were unclear, even though I had the ideas in my mind. The most important decision came from a simple question I hadn't fully answered: can one person be both a client and a professional?
I went with a single account with a base client role, with the ability to activate a professional profile from the dashboard later. Same pattern as LinkedIn.

Step 2 — Defining the MVP scope

With the corrected flow, we mapped out all the features. Then we cut ruthlessly.

What's in the MVP:

Landing page
Sign up / Log in + email verification
Public directory with search and filters
Professional public profile
Unified dashboard with role toggle
Professional onboarding (4-step flow)
Basic chat

What's out (v2):

Admin panel for profile moderation
Payments
Geolocation / map view
Emergency button
Push notifications

The Admin Panel was a tough cut — it was in my original diagram and it's genuinely important for safety. But it adds significant complexity and the MVP can function without it (profiles go live directly). It'll be the first thing added in v2.

Step 3 — Stack decisions (and why)

I was already planning to use Next.js + Supabase, but I took the time to articulate why:

Next.js — the professional directory needs to be indexed by Google. If someone searches "female electrician Barcelona", I want HandyFEM to show up. That requires SSR, which React alone doesn't give you. Next.js also has API routes built in, so no separate backend for simple logic.
Supabase — covers auth, PostgreSQL, realtime (for chat), and storage (for profile photos and portfolio) in one service. It has a generous free tier for an MVP and integrates cleanly with Next.js.
shadcn/ui — component library that copies code directly into your project rather than installing as a dependency. Accessible by default, unstyled, and you apply your own design tokens. Very common in Next.js projects right now.
Tailwind CSS — utility-first styling that works perfectly with shadcn.

Step 4 — Writing the specs

This is where most of the session went.
I've been experimenting with a specs-driven development approach — writing detailed specifications for each screen and component before writing any code. The idea is that a well-written spec becomes the prompt for Claude Design, and a well-prompted Claude Design produces clean, copy-paste-ready code on the first try.

For each component in the Design System, we documented:

All variants and sizes
All states (default, hover, focus, error, disabled, loading)
Exact color tokens
Accessibility requirements (aria labels, focus rings, touch targets)
shadcn/ui implementation notes

And for each screen:

Layout and sections
All interactive elements
All states (loading skeletons, empty states, error states)
SEO considerations
Technical notes for Supabase queries

The full spec document is saved in /docs in the project repo.

What I learned

Specs are not overhead — they are the work. The time I spent writing specs today will save me hours of refactoring later. And they double as documentation, which makes the project look serious in a portfolio context.
Claude works best as a thinking partner, not an autocomplete. The most valuable moments weren't when it generated content — they were when it pushed back on my decisions or asked clarifying questions I hadn't considered.
Cut early, cut ruthlessly. Every feature that goes into an MVP is a feature that needs to be designed, built, tested, and maintained. The Admin Panel will be better in v2 anyway — I'll have real users to learn from.

What's next
Next post: taking all of this into Jira — turning the specs into epics, stories, and tasks so the build phase has clear structure.
After that: the Design System in code, and then building screen by screen.

From Idea to Specs: Planning HandyFEM's Architecture with Claude.ai - Specs Driven development.

Constanza Diaz — Fri, 29 May 2026 14:44:53 +0000

What is HandyFEM?

The problem with jumping straight into code

Step 1 — Reviewing the user flow

Step 2 — Defining the MVP scope

With the corrected flow, we mapped out all the features. Then we cut ruthlessly.

What's in the MVP:

Landing page

Sign up / Log in + email verification
Public directory with search and filters
Professional public profile
Unified dashboard with role toggle
Professional onboarding (4-step flow)
Basic chat

What's out (v2):

Admin panel for profile moderation
Payments
Geolocation / map view
Emergency button
Push notifications The Admin Panel was a tough cut — it was in my original diagram and it's genuinely important for safety. But it adds significant complexity and the MVP can function without it (profiles go live directly). It'll be the first thing added in v2.

Step 3 — Stack decisions (and why)

I was already planning to use Next.js + Supabase, but I took the time to articulate why:

Next.js — the professional directory needs to be indexed by Google. If someone searches "female electrician Barcelona", I want HandyFEM to show up. That requires SSR, which React alone doesn't give you. Next.js also has API routes built in, so no separate backend for simple logic.
Supabase — covers auth, PostgreSQL, realtime (for chat), and storage (for profile photos and portfolio) in one service. It has a generous free tier for an MVP and integrates cleanly with Next.js.
shadcn/ui — component library that copies code directly into your project rather than installing as a dependency. Accessible by default, unstyled, and you apply your own design tokens. Very common in Next.js projects right now.
Tailwind CSS — utility-first styling that works perfectly with shadcn.

Step 4 — Writing the specs

For each component in the Design System, we documented:

All variants and sizes
All states (default, hover, focus, error, disabled, loading)
Exact color tokens
Accessibility requirements (aria labels, focus rings, touch targets)
shadcn/ui implementation notes

And for each screen:

Layout and sections
All interactive elements
All states (loading skeletons, empty states, error states)
SEO considerations
Technical notes for Supabase queries

The full spec document is saved in /docs in the project repo.

What I learned

Specs are not overhead — they are the work. The time I spent writing specs today will save me hours of refactoring later. And they double as documentation, which makes the project look serious in a portfolio context.
Claude works best as a thinking partner, not an autocomplete. The most valuable moments weren't when it generated content — they were when it pushed back on my decisions or asked clarifying questions I hadn't considered.
Cut early, cut ruthlessly. Every feature that goes into an MVP is a feature that needs to be designed, built, tested, and maintained. The Admin Panel will be better in v2 anyway — I'll have real users to learn from.

What's next
Next post: taking all of this into Jira — turning the specs into epics, stories, and tasks so the build phase has clear structure.

After that: the Design System in code, and then building screen by screen.

📚 HandyFEM App Series

🔗 Previous: From Prompt to Practical: Evolving HandyFEM’s User Flow with Claude + Mermaid
🔗 Next: Building HandyFEM’s Design System with Claude.ai: Specs, Components, and Visual Previews

From Prompt to Practical: Evolving HandyFEM’s User Flow with Claude.ai + Mermaid.live

Constanza Diaz — Wed, 15 Oct 2025 12:14:42 +0000

In my previous post about HandyFEM user flow I used Figma and ChatGPT to create a user flow for may app. This time I asked claude.ai, and I've got a much more complete version.
First of all I explained Claude all about my app, and I tried creating a prompt to create my chart in RapidChart, because I saw a post about it, but unfortunately it didn't work as expected, the chart was never built, and I tried several times, I even tried to make a smaller one, but nothing was built at all.

So I asked claude.ai for alternatives to RapidChart, and I decided to give a try to Mermaid.

It gave me a good enough result, already more complete than what I've done before, but with less visual references... so I copy/pasted my previous diagram and suggested to integrate both ideas.

new diagram:

Color-coded:
Yellow = Buttons
Light blue = Forms
Teal = Screens
Purple = Decision points
Blue = Professional UI
Green = Client UI
Red = Admin UI
Gray = System processes

The diagram shows the actual interface elements and navigation flow, making it practical for your developers to reference when building the app!

(Disclaimer: I had to iterate a few times in Claude, to get the correct flow, as the admin flow was incomplete).

The following image is just an unreadable screenshot for a reference, it was too large to attach in real size:

UI/Navigation flow and User journey flow:

View fullsize.

From Prompt to Practical: Evolving HandyFEM’s User Flow with Claude.ai + Mermaid.live

Constanza Diaz — Tue, 14 Oct 2025 21:43:23 +0000

I’m building HandyFEM, a directory + marketplace connecting women professionals in construction and repairs with clients. In my previous post, I sketched an initial user flow using Figma and ChatGPT. This time I pushed further: I briefed Claude with the full app context and iterated toward a color-coded, developer-ready UI/navigation diagram using Mermaid.

This post documents what I tried, what failed, and what finally worked—so you can reproduce the setup without losing hours to tooling dead ends.

Goal

Create a single source of truth for HandyFEM’s navigation and user journeys—clear enough for stakeholders, and concrete enough for developers to implement screens, forms, and decisions.

Attempt 1: RapidChart (didn’t pan out)

I first tried to auto-generate the diagram via RapidChart prompts. Multiple attempts—including smaller subsets—didn’t render a chart at all. Interesting idea, but in my case it wasn’t reliable enough to ship.

Tooling takeaway: if your diagram generator is brittle, switch to a text-based standard you can version-control.

Pivot: Mermaid for reproducible, versioned diagrams

Claude suggested alternatives, and I decided to give Mermaid a try. It immediately produced a decent first draft—already more complete than my earlier diagram, even if it lacked some visual cues.

To enrich it, I pasted my previous flow and asked Claude to integrate both. That gave me structure + detail.

The final diagram (color-coded for quick scanning)

Legend:

Yellow = Buttons.
Light blue = Forms.
Teal = Screens.
Purple = Decision points.
Blue = Professional UI.
Green = Client UI.
Red = Admin UI.
Gray = System processes.

This mapping keeps discussions concrete. Designers and developers can point to the exact element in the flow and agree on behavior.

Note: I iterated a few times in Claude to complete the admin path.

The image below is a small screenshot just for reference.

UI/Navigation flow and User journey flow:

Full size:

Minimal, reproducible snippet (Mermaid)

Here’s a simplified fragment that captures the pattern I used—screens, forms, decisions, and role-scoped branches. You can drop this into any Mermaid-enabled markdown and expand it for your app.

flowchart TD
  %% Legend-inspired classes
  classDef screen fill:#0fb,stroke:#066;       %% Teal
  classDef form fill:#b3e5fc,stroke:#0288d1;   %% Light blue
  classDef decision fill:#b39ddb,stroke:#512da8; %% Purple
  classDef button fill:#ffeb3b,stroke:#f57f17; %% Yellow
  classDef pro fill:#90caf9,stroke:#1565c0;    %% Blue (Professional UI)
  classDef cli fill:#a5d6a7,stroke:#2e7d32;    %% Green (Client UI)
  classDef admin fill:#ef9a9a,stroke:#c62828;  %% Red (Admin UI)
  classDef system fill:#bdbdbd,stroke:#616161; %% Gray (System)

  %% Entry
  A[Landing Screen]:::screen --> B{Choose role}:::decision

  %% Client path
  B -->|Client| C[Client Dashboard]:::screen
  C --> D[Search Professionals Form]:::form
  D --> E[Results Screen]:::screen
  E --> F[Request Quote Button]:::button
  F --> G[Request Form]:::form
  G --> H[System: Notify matched pros]:::system

  %% Professional path
  B -->|Professional| P[Pro Dashboard]:::screen
  P --> Q[Complete Profile Form]:::form
  Q --> R[Verify Identity Button]:::button
  R --> S[System: KYC check]:::system
  S --> T{Approved?}:::decision
  T -->|Yes| U[Receive job requests]:::screen
  T -->|No| V[Manual review]:::admin

  %% Admin path
  B -->|Admin| A1[Admin Panel]:::admin
  A1 --> A2[Moderate Listings]:::admin
  A1 --> A3[Resolve Disputes]:::admin

Why this helps:

Text-as-diagram means you can version the flow in Git, review it in pull requests, and co-edit with your team.
Color classes encode semantics you can reuse across large diagrams.
Branching by role makes gaps obvious and audit-able.

Practical notes

Prompt shape matters. My best results came from supplying Claude with the app glossary, roles, and UI primitives (screen, form, decision, button, system).
Iterate role by role. I filled Client and Professional paths first, then Admin.
Keep it modular. Break huge flows into linked sub-diagrams per feature if your tool or host chokes on size.
Treat it like code. Store the .md or .mmd in your repo and make changes via PRs.

What I’ll do next

Split the mega-diagram into feature-level Mermaid files.
Connect each node to issue links or Figma frames for implementation hand-off.
Add acceptance criteria to decisions and forms to reduce ambiguity during dev.

If you’re mapping a complex app, pairing a capable LLM with Mermaid gives you speed, structure, and a durable artifact your team can actually build from.

👉 This post opens the series on building HandyFEM from scratch. The upcoming entries will cover Jira planning, Sprint 0 setup, and the integration of Vercel v0 into the workflow. Follow the hashtag #HandyFEMapp if you don’t want to miss the progress!

📚 HandyFEM App Series

🔗 Previous: Building a Full Stack Web App from scratch: First Steps

🔗 Next: From Idea to Specs: Planning HandyFEM's Architecture with Claude.ai - Specs Driven development.

DEV Community: Constanza Diaz

How I Built My Design System from a Color Palette (with Claude Code and tweakcn)

The starting point: I had colors, not a system

Discovering tweakcn

The workflow

Back to Claude Code

Takeaway: why this workflow works

Multilanguage good practices.

My i18n Setup Was Right. Until It Wasn't.

AI Pair Programming Isn't Autopilot: Scaffolding HandyFEM and Catching What the AI Threw Away

The agent writes the code. You're still the engineer.

The task: scaffolding the project

The catch

Why this matters

Honest reflections on the workflow

Takeaway

Security by Design: Keeping API Tokens Out of Git with a 3-Layer Setup

Defense in depth

Layer 1 — .gitignore

Layer 2 — the pre-commit hook

Layer 3 — environment variables

Testing it

Takeaway

🏷️ All posts in this series: #HandyFEMApp

Security by Design: Keeping API Tokens Out of Git with a 3-Layer Setup

Defense in depth

Layer 1 — .gitignore

Layer 2 — the pre-commit hook

Layer 3 — environment variables

Testing it

Takeaway

🏷️ All posts in this series: #HandyFEMApp

Security by Design: Keeping API Tokens Out of Git with a 3-Layer Setup

Defense in depth

Layer 1 — .gitignore

Layer 2 — the pre-commit hook

Layer 3 — environment variables

Testing it

Takeaway

📚 HandyFEM App Series

🏷️ All posts in this series: #HandyFEMApp

From Specs to Tickets: Automating Jira Setup with Node.js and the Jira API

The plan was simple

Why automate Jira setup at all?

Problem 1 — Jira Spaces ≠ Jira Classic

Problem 2 — The API token wasn't the issue (until it was)

Problem 3 — customfield_10014 doesn't exist in team-managed projects

Problem 4 — Board search doesn't work for team-managed projects

What the final setup looks like

Security: never hardcode tokens

What I'd do differently

The scripts

📚 HandyFEM App Series

Building HandyFEM's Design System with Claude.ai — Specs, Components and Visual Previews

What is a Design System and why build it first?

The token decisions: here are some design desicions.

Colors

Spacing

Border radius

The components

DS-01 — Button

DS-02 — Inputs

DS-03 — Professional Cards

DS-04 — Badges and Chips

DS-05 — Avatar

The workflow: spec → visual preview → approve → document

What the spec document looks like

The interaction details

What's next

📚 HandyFEM App Series

From Idea to Specs: Planning HandyFEM's Architecture with Claude.ai - Specs Driven development.

What is HandyFEM?

The problem with jumping straight into code

Step 1 — Reviewing the user flow

Step 2 — Defining the MVP scope

What's in the MVP:

What's out (v2):

Step 3 — Stack decisions (and why)

Step 4 — Writing the specs

What I learned

Layer 1 — `.gitignore`

Layer 2 — the `pre-commit` hook

Layer 1 — `.gitignore`

Layer 2 — the `pre-commit` hook

Layer 1 — `.gitignore`

Layer 2 — the `pre-commit` hook

Problem 3 — `customfield_10014` doesn't exist in team-managed projects