[🤖] The Design Kept Changing: Why I Needed DESIGN.md

✨ GPT-5.6 Sol’s Summary

The brochure came out differently every time, which led me to DESIGN.md. But I had already felt the need for design consistency in other personal projects and had been applying it in my own way. This is a record of connecting those scattered standards in a format AI can keep reading.

The Design Changed Every Time I Made a Brochure

After returning from a long holiday, I continued working on a brochure at my current company. After spending so much time managing coordinators and workers that I failed to finish the brochure on time, I simplified the workflow, but the design still bothered me. Even within the same PPT, the mood shifted from page to page, and every new version generated a new design.

My other projects were not very different. I tried to create consistency by having AI search for design references and good examples or by sharing them myself. Sometimes I simply hoped the random gacha pull would be good. What came back was nothing but D-grade gacha that reeked of AI and had no consistency at all.

I did not want to generate one vaguely attractive screen at a time. I wanted the same colors, type hierarchy, spacing, and component sensibility to carry over to the next page and the next version. The brochure had no such standard. Every time AI received a reference, it had to guess the mood again from scratch.

This Was Not the First Time I Had Seen the Problem

Looking back, this was not the first time I had felt the need for design consistency. In July 2025, I had already written about how to build a design system for vibe coding. Even then, I was thinking about a process of designing with Figma AI, saving screens and code as references, organizing typography and color palettes, and comparing them with the actual output.

I did more than think about it in Tadak Bible. Starting in January 2026, I began gathering colors, typography, and themes in one place. I documented directions such as pastel blue and lavender, a calm and warm atmosphere, and readability on the Bible typing screen. Later, I created BibleColors, BibleTypography, spacing, corner, icon, and motion tokens and applied them across multiple screens. I also added checks so new screens could not invent arbitrary colors and font sizes again.

In other words, I already knew why a design system was necessary. Inside Tadak Bible, I had gone quite far toward binding the product’s colors, fonts, and shared components through code and documentation.

The problem was that this experience did not carry over to other projects and deliverables. Tadak Bible’s standards were scattered across its documents, Flutter code, and checks. There was no shared format that an AI starting a new web project or PPT could immediately read and use to continue the same sensibility. For every project, I searched for references again, threw in more examples, and waited for a good result again.

I Tried to Connect the Scattered Standards with DESIGN.md

Then I found the ko/design.md catalog, which organizes Korean services’ design systems as LLM context,¹ and Google Labs Code’s DESIGN.md repository.²

The name and examples gave me a rough sense of what the file was. It seemed to be a place to record colors, fonts, spacing, components, and the overall atmosphere so AI could refer to them whenever it created a design. I thought I could move the design standards I had already built for Tadak Bible into a form that an Agent could keep reading and then manage other projects in the same way.

The problem was that I once again glossed over the details. I told AI to find out what DESIGN.md was, study the examples, and make something similar. Then I moved on, assuming it had researched enough and applied enough. I did not personally check the scope described by the official documentation, whether the generated file respected that scope, or whether the actual output had become visually consistent.

The fact that AI read a link and produced a plausible file was not the same as having the design standard I wanted. Failing to check that difference was my mistake.

I Nearly Put the Entire Product Plan into DESIGN.md

Without properly checking the scope of DESIGN.md, I tried to put every user’s screens and flows, states, permissions, and recovery paths into DESIGN.md for my next product plan. Codex accepted that expansion as-is and began creating role-specific DESIGN.md files and separate rules.

Something felt wrong. It did not seem to be handling the UI properly, so I told it again to start by checking the Google Labs Code example I had emphasized most.

After reading the original material, the boundary became much clearer. Google Labs Code’s DESIGN.md is a format that continually communicates a product’s visual identity to a coding Agent. The YAML can hold precise design tokens, while the Markdown body explains why those colors, fonts, and shapes are used and how the overall design should look, feel, and behave.³

That word, “behave,” did not mean absorbing the entire product plan. User roles, journeys, permissions, exceptions, recovery, screen structure, and verification still belonged in ordinary product documentation. The role-specific details I had first tried to create were not useless; they simply belonged under regular docs/, not under the name DESIGN.md.

Following the Format Is Not the Same as Copying the Design

Once I corrected the boundary, there was one more thing to check. Using Google Labs Code as the standard did not mean copying the example design from its repository into every project.

Google provided the DESIGN.md format and a way to interpret it, not the design content itself. The colors, fonts, and atmosphere in the examples belonged to those examples’ visual identities. A real project’s DESIGN.md should contain visual standards derived from that product’s users, environment, brand, and the references I chose. The ko/design.md catalog is also material for reference and comparison; copying any design from it does not automatically create our product’s identity.

So I revised the shared rules and the product planning Skill. DESIGN.md would be created only when visual identity was actually in scope, while roles, journeys, permissions, recovery, and detailed screen design would remain in ordinary product documentation. I removed the role-specific DESIGN.md direction I had invented, and the final template passed Google’s official validation.

This time, while trying to reduce design gacha, I handed the meaning of DESIGN.md over to AI gacha as well. If I give AI a link, say “research and apply it,” and trust the result just because a file exists, AI fills every blank I failed to check in its own way.

A DESIGN.md file alone does not automatically produce good design. For a PPT in particular, I still need actual slide masters and layout samples, and I need to inspect the rendered output to see whether it follows those standards. But if I leave the visual standards I have accepted for each product in a canonical DESIGN.md, at least AI will have fewer chances to redraw the mood from a blank screen every time.

I had understood the need for design consistency for a long time. I was already building a design system in Tadak Bible. Only now did I find an Agent-readable format that could carry that experience into other projects and deliverables, and finally connect it to the name DESIGN.md.

References

1. ko/design.md, a catalog of Korean service design systems. It provides signature designs from Korean services as LLM context. ↩

2. Google Labs Code, DESIGN.md. It introduces a visual-identity format that coding Agents can refer to continuously. ↩

3. Google Labs Code, DESIGN.md specification. It defines the structure, standard sections, and validation rules for YAML design tokens and Markdown design rationale. ↩