How Gemini CLI actually loads context
Three tiers, concatenated in order on every prompt. ~/.gemini/GEMINI.md holds your global defaults. From the directory you launch in, the CLI walks up to the project root (the folder with .git) collecting project GEMINI.md files. Component directories can add their own for local context. The /memory show command prints the assembled result verbatim, /memory refresh re-scans after edits, and @file.md inside any GEMINI.md imports another file, relative or absolute paths both work.
There is no relevance matching in this pipeline: everything found is always loaded. That cuts both ways. Long exploratory notes don't belong in GEMINI.md, but a design contract does, because design applies to every UI request and the failure mode of *not* loading it is the drift you're here to fix.
The failure mode without one
Ask Gemini CLI to build screens across a few sessions with no written contract and it re-decides the visual language each time: a new accent, slightly different spacing, another font pairing. Not because the model is weak, but because nothing persists its earlier choices. The statistical default it falls back to is the same one every model shares, which is why unguided AI apps converge on the same look.
Consistency check · Ad-hoc colors
The same plan card, built two ways in Ambient Sage.
Pricing
Everything a small team needs to ship a branded UI.
Pricing
Everything a small team needs to ship a branded UI.
The setup
- 1
Install a kit's tokens
Semantic CSS variables or a Tailwind theme in the repo, so token names resolve to real values the code can use.
- 2
Add DESIGN.md at the project root
The full written system: what each color role means, the type scale, spacing, motifs, and the do-not rules. This is the file that carries identity across sessions.
- 3
Import it from the project GEMINI.md
One section, mostly one import line. The hierarchy does the rest: every prompt in the project now carries the contract.
- 4
Verify with /memory show
Run it once and read the output. If DESIGN.md's content is not in there, the import path is wrong, and no amount of prompting will fix what never loaded.
# Design system
@DESIGN.md
- Use only the semantic tokens defined above; never a literal hex
value or an ad-hoc font.
- Type, spacing, and radii come from the scales in DESIGN.md.
- If a needed value has no token, stop and ask.Keep the global file out of it
Design contracts are per-project by nature. Put the import in the project GEMINI.md, not ~/.gemini/GEMINI.md, or every repo you open inherits one product's brand.
Optional: MCP, so Gemini can apply kits itself
Gemini CLI supports MCP servers via ~/.gemini/settings.json. With the Identity Forge server registered, the agent can search the kit catalog, read complete token systems, and write DESIGN.md plus tokens into the repo as a tool call instead of you assembling the files by hand:
npx --yes identityforge@latest install --client geminiA complete DESIGN.md, ready to import
Every Identity Forge kit exports the file this setup depends on: 28 semantic tokens in light and dark, typography, spacing, motifs, and agent rules.
Does Gemini CLI have a design system feature?
No native one. Its GEMINI.md context hierarchy is the mechanism: files load on every prompt, and the @file.md import syntax pulls a DESIGN.md straight into that context. Paired with installed tokens, it covers what a native feature would.
Where does GEMINI.md go?
Three tiers: ~/.gemini/GEMINI.md globally, a GEMINI.md at (or above) your working directory for the project, and optional per-subdirectory files. All found files are concatenated in that order on every prompt. Design rules belong at the project tier.
How do I check the design rules actually loaded?
/memory show prints the exact concatenated context sent to the model; your DESIGN.md content should appear in it. After editing files, /memory refresh re-scans. This one check catches nearly every broken setup, usually a wrong import path.
Why not paste the whole design system into GEMINI.md directly?
It works, but it forks the truth: the system then lives in two places once you also need it for other agents or human docs. Keeping DESIGN.md as the single artifact and importing it with @DESIGN.md means every tool, and every teammate, reads the same file.
Can Gemini CLI apply an Identity Forge kit?
Yes. Without MCP, the CLI command identityforge apply <kit> writes the DESIGN.md and tokens into the repo. With the MCP server registered in ~/.gemini/settings.json, Gemini can search, preview, and apply kits itself during a session.