Een website zonder sjabloon met Claude Code en Refero DESIGN.md

Praktische materialen over werken met projecten en modellen: Ailoot-documentatie.

Waarom lijken websites van Claude Code op Tailwind-sjablonen?#

In het beschreven voorbeeld uit januari werd een klein zijproject gemaakt: een dialer voor koude acquisitie. In een lege repository kreeg Claude Code de opdracht om de startpagina te bouwen. Het resultaat was generiek: een donkere achtergrond in slate-950, een accentkleur in purple-500, een vetgedrukte schreefloze kop en daaronder drie kaarten met identieke schaduwen. Dezelfde lay-out als bij de eerste release van ChatGPT, de eerste release van Lovable en de eerste release van v0. Na vijf aanpassingen van de prompt met toevoegingen als “modern”, “premium” en “anders dan alle andere” veranderde er niets. De pagina zag er nog steeds uit alsof die uit een verzameling Tailwind UI Templates kwam.

Dat wil zeggen: Claude “weet” niet níét hoe je iets moois maakt. Het weet wat de meeste mensen doen en reproduceert die meerderheid. Voor een resultaat dat niet gemiddeld is, heeft de agent specifieke randvoorwaarden nodig: welke kleuren, lettertypen en tussenruimtes gebruikt moeten worden en welke componenten als canoniek gelden.

Daar komt een ontwerpsysteem als context van pas. Niet “maak het mooi”, maar “maak het in deze specifieke stijl; dit zijn de parameters”.

Refero Styles overbrugt die kloof met een kant-en-klaar artefact: een bestand DESIGN.md met parameters van echte producten.

Wat is Refero Styles?#

De startpagina van styles.refero.design zegt het rechtstreeks: “ontdek meer dan 2,000 door AI-agents leesbare ontwerpsystemen van toonaangevende productwebsites.” In de catalogus staan merken die de visuele standaard bepalen: Apple, Linear, Stripe, Notion, Vercel, ElevenLabs, Mercury, PostHog, xAI, Modal, Duolingo. Ze worden niet handmatig geëxtraheerd: het Refero-team voert een script uit dat de daadwerkelijke CSS en markup van een site analyseert en het resultaat verpakt in gestructureerde markdown. De bibliotheek van styles.refero.design zelf is gratis.

Het sleutelwoord is “gestructureerd”. Het bestand bevat geen screenshots en ook geen beschrijving als “in een minimalistische stijl”. Het is markdown met specifieke hex-kleuren, exacte lettergroottes in pt, eenheden voor tussenruimtes en regels voor componenten. De AI-agent leest dit bestand en werkt met concrete details in plaats van te proberen smaak in woorden te beschrijven.

Op de pagina ai-agents noemt het Refero-team de ondersteunde tools: “Cursor, Claude Code, Codex, v0 en Lovable.” Met andere woorden: DESIGN.md werkt als een universeel artefact — één bestand dat geschikt is voor alle belangrijke AI-ontwikkelagents.

Wat staat er in een DESIGN.md?#

Het Refero-team beschrijft de bestandsstructuur op de pagina design-md-template als volgt:

De bestandsstructuur ziet er meestal ongeveer zo uit:

De makers benadrukken ook een principe dat 80% van de AI-ontwerpproblemen oplost:

Dat wil zeggen: de hex-code #5E6AD2 is krachtiger dan “zoals Linear”. De exacte waarde font-size: 13px / line-height: 18px is krachtiger dan “compacte tekst”. Specificiteit wint van interpretatie.

DESIGN.md in de repository is geen afbeelding voor het team. Het is een bouwsteen van de permanente context van je project: gestructureerde kennis die AI bij elke aanvraag leest.

In 4 stappen een website in de stijl van Linear maken#

Deze vier stappen vormen de beschreven reeks om een nieuwe website te starten. Niet “vier stappen in het algemeen”, maar een specifieke reeks met één handeling per stap.

1. Installeer Claude Code

   Native installer met één opdracht: curl -fsSL https://claude.ai/install.sh | bash (de aanbevolen methode in de officiële documentatie). Op macOS werkt brew install --cask claude-code; op Windows winget install Anthropic.ClaudeCode. Als het al is geïnstalleerd, controleer dan de versie: claude --version (2.1.178+ is nodig — in deze versie zijn Tool(param:value)-machtigingen en het blokkeren van gevaarlijke git-opdrachten in de automatische modus geïntroduceerd). Meld je aan bij je account: claude start de configuratiewizard. Claude Code is inbegrepen bij een Pro-abonnement ($17 per maand bij jaarlijkse betaling of $20 per maand bij maandelijkse betaling).

2. Open Refero Styles en kies een merk

   Ga naar https://styles.refero.design en open de catalogus. Het belangrijkste selectiecriterium is hoe goed de stijl bij je product past, niet of je “de look mooi vindt”. Bouw je een SaaS-dashboard? Bekijk Linear, Vercel en Notion. Bouw je een fintechproduct? Bekijk Stripe, Mercury en Column. Bouw je een product voor leden? Bekijk Duolingo. Open een merkkaart en klik op “Copy DESIGN.md”.

3. Plaats DESIGN.md als context in het project

   Maak in de hoofdmap van het project een bestand docs/DESIGN.md en plak de gekopieerde inhoud erin. Open daarna CLAUDE.md en voeg één regel toe: @docs/DESIGN.md. Dit is een importinstructie — Claude Code laadt de inhoud in de context wanneer een sessie start. Lees voor meer informatie over imports in CLAUDE.md de handleiding voor één instructiebestand voor Claude Code, Codex en Cursor.

4. Geef een prompt voor een specifieke pagina

   Niet “maak het mooi”. Wees specifiek: “Bouw met de DESIGN.md in de context een startpagina voor een SaaS-product voor taakbeheer. Structuur: hero met een kop en subkop, twee CTA-knoppen (primair en secundair), daaronder een blok met 3 functies en pictogrammen, en vervolgens een blok met testimonials. Gebruik exact de kleuren en typografie uit DESIGN.md; verzin zelf niets.”

Na de vierde stap bouwt Claude de pagina. In de beschreven ervaring duurt het gemiddeld 8–12 minuten om een startpagina te maken — en die lijkt echt op de stijl van het gekozen merk. Geen pixelperfecte kopie, maar wel een herkenbare esthetiek: dezelfde lettertypen, hetzelfde palet, hetzelfde ritme van tussenruimtes en dezelfde kleine keuzes in de knoppen.

De makers van Refero beschrijven hetzelfde principe in drie stappen iets beknopter op hun pagina ai-agents/design-resources:

Deze reeks van vier stappen volgt dezelfde logica, met als expliciete toevoegingen het installeren van Claude Code en het importeren van het bestand in CLAUDE.md.

Welke stijl kies je voor je product?#

De makers van Refero geven dit advies al in de eerste stap van hun handleiding: kies een referentie niet alleen op basis van de merknaam, maar ook op basis van dichtheid, toon en doelgroep.

Wat betekent dit in de praktijk? Van Apple afgeleide kleuren, typografie, hiërarchie en ingetogen beweging kunnen bij een SaaS-dashboard passen, terwijl ruime opmaak van een specifieke productmarketingpagina minder geschikt kan zijn. Bekijk de concrete referentie in plaats van alleen de merknaam. Stel voor een boekhouddashboard compacte rijhoogten, afstanden en informatiedichtheid expliciet in en behoud leesbare cijfers en bediening; kopieer een ruime presentatielay-out niet ongewijzigd.

Een eenvoudige gids voor de keuze op basis van het producttype:

Twijfel je nog steeds, kies dan Linear. Het heeft de meest veelzijdige basis: een neutraal palet, leesbare typografie (Inter / Söhne) en ingetogen tussenruimtes. Een website op basis van Linear ziet er professioneel uit voor 9 van de 10 producttypen.

Waarom DESIGN.md opnemen in de permanente context van je project?#

In de beschreven werkwijze wordt DESIGN.md in elk project met AI-agents naast CLAUDE.md opgeslagen. Het bestand wordt niet gezien als “tijdelijk voor één taak”. Het is een permanente canon waarop alle toekomstige sessies steunen. Over een maand kun je Claude vragen om een nieuwe pagina aan het project toe te voegen — het opent dezelfde DESIGN.md en bouwt in dezelfde stijl. Over zes maanden kun je het project aan een ander teamlid overdragen — die kan Claude ook uitvoeren en een consistent resultaat krijgen, omdat DESIGN.md in de repository staat.

Voor ontwerp werkt het principe als volgt: één keer wordt een beslissing genomen over het palet, de typografie en het ritme van tussenruimtes. Daarna neemt elke AI-agent die als gegeven aan.

Dat betekent dat ontwerp als code leeft (markdown is code), niet als een Figma-bestand dat AI niet kan lezen. Staat het ontwerp als bestand in de repository, dan kan Claude Code het lezen, Codex kan het lezen en elk toekomstig hulpmiddel kan het lezen. Staat het ontwerp in Figma, dan leeft het in een aparte omgeving en moet het voor elke sessie handmatig worden vertaald.

In de beschreven zijprojecten werd deze structuur gebruikt:

project/
├── CLAUDE.md            (imports @docs/DESIGN.md)
├── docs/
│   ├── DESIGN.md        (visual canon, copied from Refero)
│   ├── ARCHITECTURE.md  (project structure)
│   └── BRAND.md         (tone of voice, vocabulary)
└── ...

Deze drie bestanden zijn één manier om de permanente context van het project te organiseren. DESIGN.md regelt het visuele aspect, ARCHITECTURE.md de structuur en BRAND.md de stem. Elke AI-agent met toegang tot de repository krijgt ze alle drie als context.

Wat zijn Refero MCP en refero_skill?#

Refero Styles is de basislaag (DESIGN.md als bestand). De volgende golf bestaat uit integraties die toegang tot de bibliotheek “native” maken voor AI-agents.

Refero MCP (officieel). Dit is een server-API op https://api.refero.design/mcp waarmee Claude Code verbinding maakt via een bearer-token. De agent krijgt dan toegang tot meer dan 150,000 schermen en 6,000 gebruikersstromen van echte producten. Je kunt het installeren met een skill:

npx skills add https://github.com/referodesign/refero_skill --skill refero-design

Na de installatie start Claude aan het begin van elke sessie “design research” als verplichte eerste stap: het bekijkt welke visuele keuzes bij de taak passen en stelt zo nodig drie richtingen voor die gekoppeld zijn aan de gekozen referentie. Op 23 juni 2026 heeft de refero_skill-repository 67 commits en 135 sterren. Een nieuw product dat actief wordt ontwikkeld.

In de beschreven werkwijze wordt een eenvoudige aanpak gebruikt: open de site handmatig, kopieer DESIGN.md en zet het in een bestand. MCP is nuttig wanneer werken met ontwerpsystemen routine wordt — bijvoorbeeld wanneer je meerdere klantprojecten beheert en elke dag tussen visuele canons wisselt. Lees voor meer informatie over het verbinden van MCP-servers met Claude Code de handleiding over NotebookLM en MCP.

Welke 4 fouten verstoren de werkwijze?#

Deze vier fouten komen naar voren in de beschreven ervaring met ontwerpcontext. Elke fout lijkt onschuldig, maar brengt het resultaat terug naar het standaard Tailwind-sjabloon.

Fout 1. De prompt “maak het modern”. Dit is het meest voorkomende foutpatroon. Mensen openen Claude Code en schrijven: “maak een SaaS-website voor me, moderne stijl, premium uitstraling”. Ze krijgen een donkere achtergrond plus een paars accent. In de trainingsdata hangt het woord “modern” samen met alle landingspagina’s uit 2022–2024 die met hetzelfde sjabloon zijn gebouwd. Zonder de exacte parameters uit DESIGN.md betekent “modern” dus “gemiddeld”.

Fout 2. DESIGN.md als bericht in de chat plakken. Soms kopiëren mensen DESIGN.md naar het chatvenster van Claude Code en zeggen: “hier is de stijl, gebruik die”. Dat werkt één keer — tot het einde van de sessie. Open een nieuwe sessie (of schakel over naar een andere taak, /clear) en de context is verdwenen. Wil je de stijl behouden, dan moet het bestand in de repository staan en in CLAUDE.md worden geïmporteerd. Lees voor meer informatie over waarom CLAUDE.md de plek is voor permanente context de handleiding over Claude-geheugen.

Fout 3. Een stijl kiezen omdat je die “mooi vindt”. Een ruime Apple-marketingreferentie kan ongeschikt zijn om ongewijzigd naar een makelaarsdashboard met 30 aanbiedingen op het scherm te kopiëren. Dat sluit Apple-typografie, -palet of -hiërarchie niet uit: pas afstanden en rijdichtheid aan de taak aan en controleer de echt zichtbare informatie op het doelscherm. Kies de specifieke referentie op dichtheid, toon en doelgroep, niet alleen op merknaam.

Fout 4. DESIGN.md niet in de prompt zelf noemen. DESIGN.md kan in de repository staan, via CLAUDE.md zijn geïmporteerd en zichtbaar zijn voor de agent. Maar als de prompt zegt “bouw een website”, kan Claude de gebruikelijke aanpak volgen zonder expliciet naar het bestand te verwijzen. Voor elke ontwerpprompt is deze zin nuttig: “Gebruik exact de kleuren, lettertypen en tussenruimtes uit docs/DESIGN.md. Verzin zelf geen waarden — neem ze over uit het bestand.” Zo zorg je ervoor dat de agent DESIGN.md gebruikt in plaats van het over te slaan.

Exacte tokens zijn hex-codes, lettergroottes in pt en eenheden voor tussenruimtes in DESIGN.md. Natuurlijke taal betekent “modern”, “premium”, “strak” of “zoals Apple”. Exacte tokens werken; vrije bewoordingen niet.

Wat kun je hierna doen?#

Je hebt nu de basiswerkwijze: Claude Code + DESIGN.md van Refero + 4 stappen = een website zonder sjabloon. Dit dekt 70% van de behoeften. De overige 30% betreft situaties waarin je meer precisie, meer snelheid of verificatie nodig hebt.

Drie richtingen om na het beheersen van de basis verder te verkennen:

1. Frontend Design Skill. Dit is een officiële skill voor Claude Code die visuele feedback toevoegt. De agent maakt met Puppeteer een screenshot van de opgebouwde pagina, bekijkt die met zijn “ogen” (een vision-model), vergelijkt die met DESIGN.md en stelt zelf verbeteringen voor. Dit is een geautomatiseerde cyclus van “prompt → code → screenshot → kritiek → prompt”. Handig wanneer een pagina complex is en je die niet in één iteratie goed krijgt.

2. Refero MCP in productiemodus. Beheer je 3–5 projecten tegelijk, dan wordt het omslachtig om DESIGN.md voor elk project handmatig toe te voegen. Refero MCP kan op basis van een projectbeschrijving 3 geschikte stijlen vinden en een keuze aanbieden. Dit verkort de start van een nieuw project van 30 minuten naar 3.

3. Combineren met Context Engineering. DESIGN.md is een van de contextartefacten. Daarnaast vind je meestal ARCHITECTURE.md (projectstructuur), BRAND.md (merkstem) en business/audience.md (doelgroep). Ze worden allemaal in CLAUDE.md geïmporteerd. Wanneer Claude een pagina bouwt, houdt het rekening met de visuals, de doelgroep en de productstructuur. Dit is in feite context engineering: systematisch werken aan wat je de agent geeft voordat je een verzoek indient.

Praktische materialen: Ailoot-documentatie.

Praktische materialen: Ailoot-documentatie.

Meer materialen en tools: Ailoot.