DEV Community: yuelinghuashu

LLM Narrative Engines, Part 6: Runtime Loop and Branching

yuelinghuashu — Wed, 05 Aug 2026 10:45:53 +0000

Before reading this: This is the final post in the series. I'd recommend reading the previous five — Part 1 covers the .meph format, Part 2 walks through a hands-on tutorial, Parts 3 and 4 explain how the parser outputs a domain.Contract, and Part 5 covers testing. This post assumes you already know the engine has a contract struct. The core problem we're solving: how do we drive it?

I. A Narrative Engine's Fifth Problem: How Do You Bring Rules to Life?

The parser turns contracts into structs, but structs don't tell stories. A narrative engine also needs a runtime — a complete loop of input → matching → execution → output.

Three engineering problems need solving:

How do rules match in real time? When user input arrives, the engine needs to iterate over all rules, evaluate conditions, and decide which actions to trigger — all in milliseconds, without affecting user experience.
How does the LLM follow rules? Rules can't directly constrain the LLM — they must take effect indirectly through prompts. Translating rules into a format the LLM understands is the core challenge here.
How do state and memory persist? Every turn changes the character's state and memory pool. But when the next turn starts, the engine must restore the complete state from the previous turn. Without persistence, there's no long-form narrative.

This post solves all three. Parts 4 and 5 already covered rule-matching details (two-phase matching, dice evaluation) — I won't rehash them here. Instead, I'll focus on how the runtime wires the entire pipeline together.

Once the engine has a contract, it enters a loop: receive user input → match rules → execute actions → call LLM → return response. That loop is the runtime.

But before implementing the loop, several engineering problems must be solved first — they determine whether the engine is "functional" or "usable."

II. Novel-Grade Terminal Output: Full-Width Indentation and Streaming Interception

LLM streaming output comes back in chunks. The engine intercepts each chunk via an onChunk callback and writes it directly to the terminal.

One design detail: full-width indentation (　　).

onChunk := func(chunk string) {
    for _, ch := range chunk {
        if ch == '\n' {
            fmt.Println()
            needIndent = true
            inParagraph = false
        } else {
            if !inParagraph && needIndent {
                fmt.Print("　　")  // two full-width spaces at the start of each paragraph
                needIndent = false
            }
            fmt.Print(string(ch))
            inParagraph = true
        }
    }
}

The effect: each paragraph in the terminal output starts with two full-width spaces, making it look like a printed book. This small detail dramatically improves the creator's experience — it turns "terminal output" into "novel pages."

But behind streaming output is a more critical engineering decision: the action executor handles all streaming callbacks uniformly.

State-modification actions: return results immediately, then simulate character-by-character output via callback
LLM actions: true streaming output, chunk by chunk
Static text: return immediately, then simulate streaming output

Every action ultimately outputs through onChunk, regardless of its source. This ensures a consistent terminal experience.

III. Five-Layer Sandwich Prompt: Welding Constraints at Both Ends

The biggest problem with LLM narrative is format drift — it often outputs stage-direction script format:

( smirks ) [Belial]: You're all too weak.

This breaks immersion. The solution: place format constraints at both the top and bottom of the prompt, forming a sandwich structure. In v1.1.0, the actual prompt rendering (RenderPrompt in internal/core/llm/prompt.go) has five layers:

【格式硬性要求】
(NarrativeConstraints — no parentheses, no script markers, no soliloquies)

【世界观】
(context)

【角色】
You are {角色名}, a being with {锚点风格}. Your background: {角色背景}

【当前状态】
(rendered from the runtime `map[string]any`)

【命运的推动】
(conversation history — alternating fate and assistant records)

【你记得的过往】
(dynamically accumulated memories from the runtime)

【此刻】
(user_input)

【要求】
(NarrativeConstraints, emphasized again)

Constraints appear twice, at both ends, with the context sandwiched in between. Two reasons for this:

Primacy effect: the LLM sees the constraints first — they get the highest priority
Recency effect: the constraints the LLM sees last influence the final output

Double emphasis ensures the format constraints aren't diluted by the context in the middle.

3.1 Deterministic Rendering: Sorting Guarantees Cache Hits

There's a subtle engineering problem here: Go's map iteration order is random.

At runtime, 【状态】 from the contract is converted to a map[string]any for fast read/write. When rendering 【当前状态】 in the prompt, if the iteration order changes each time, the generated prompt text changes — even if the state content is identical. This causes the LLM's KV Cache to completely miss, forcing recomputation every time.

The solution: sort the keys of state (sort.Strings) to ensure stable rendering order. When the state doesn't change, the generated prompt text is byte-for-byte identical, allowing the LLM service's KV Cache to hit, reducing latency and token consumption.

3.2 Anti-Soliloquy Constraint

NarrativeConstraints has one deliberately emphasized rule:

Each response must include dialogue and action from at least one other character (non-player). If no other characters are present in the scene, introduce or create at least one interactive object. Prohibit purely player-only soliloquies.

This solves the "empty world" problem in narrative. If the LLM only responds to player input without introducing other characters, the story becomes a monologue and loses dramatic tension. This constraint forces the LLM to introduce at least one interactive object in every response, making the world feel alive.

IV. Mother-Child Save Mechanism

After every turn, the engine automatically saves the current state to a child file.

Naming convention (v1.1.0 onward, aligned with the Flutter version, dot-separated):

Master story.meph → default child story.child.meph
Branch --branch dark → story.dark.meph

func BuildChildPath(filename string, branch string) string {
    dir := filepath.Dir(filename)
    base := filepath.Base(filename)
    ext := filepath.Ext(base)
    name := strings.TrimSuffix(base, ext)

    // Already a child file: overwrite directly (prevent nested generation)
    if isChildFileName(name) {
        return filename
    }

    if branch != "" {
        return filepath.Join(dir, name+"."+branch+ext)
    }
    return filepath.Join(dir, name+childSuffix+ext) // childSuffix = ".child"
}

isChildFileName precisely identifies existing child files: xxx.child (default child) or xxx.branchName (branch names starting with letters). This means my_story_1.meph (with a numeric suffix) won't be misidentified as a child.

A child file is a complete .meph contract, containing:

All static blocks from the master (character name, worldview, character background, opening scene, anchors, rules)
Updated 【状态】
Accumulated 【记忆】
Recent 【历史】

This means one static contract can evolve into any number of dynamic children:

story.meph (master, read-only)
    ├── story.child.meph (main timeline)
    ├── story.dark.meph (dark branch)
    ├── story.light.meph (light branch)
    └── story.experimental.meph (experimental branch)

Each branch evolves independently, without interfering with the others. The project includes data/dantes.meph alongside an already-run data/dantes.child.meph save.

Save timing: instead of writing to disk every turn (which would be inefficient), it's split into two layers:

After each turn: the Session layer (cmd/mephisto/session.go) calls engine.Save() to persist progress in real time
On exit: a defer saves one more time, ensuring the final state is written before exit

Rule freshness during save: Save() has a clever design — before saving, it reads the child file from disk (if it exists) and uses the 【规则】 block from disk as the latest rules. This means the user's real-time edits to the rules section in their editor won't be overwritten by the auto-save. This also supports rule hot-reload introduced in v1.0.3: session.go watches the child file for changes via fsnotify, with a 500ms debounce, then calls ReloadContract to re-parse — replacing only the rules while preserving state and history. This makes "edit rules → save → instantly effective" a reality.

Loading:

Default: load the child if it exists
--reset: ignore the child, start fresh from the master
--branch dark: load the corresponding branch file

Note: Running a child file directly will overwrite it — the engine treats any .meph file as a master and generates a corresponding child. To avoid losing progress, don't run run directly on child files.

The value of this design: creators can fork storylines at critical moments, exploring different directions without losing any progress.

V. Memory Extraction: Synchronous Weaving After Streaming

Memory extraction is critical for long-form narrative — it extracts key events from conversation history, compresses them for long-term storage, and injects them into the LLM context every turn.

But extraction calls the LLM, which takes seconds. If executed before streaming output, users would wait several seconds every 5 turns before seeing the first character.

The solution is simple: output first, extract later.

Here's the flow for each turn:

User input
    │
    ▼
Rule matching + action execution + LLM streaming output (user sees text appear character by character)
    │
    ▼
Streaming completes, user finishes reading the response
    │
    ▼
Engine.Run synchronously executes memory extraction (still inside Run, user has finished reading)
    │
    ▼
Return to Session — Session calls Save to auto-save the child
    │
    ▼
Show input prompt, wait for next turn

Note the difference from the old version: memory extraction runs synchronously inside engine.Run(), while child saving is handled by the Session layer after each Run returns. The two are decoupled — the engine handles narrative and memory, while Session handles persistence.

// internal/core/engine/engine.go

func (e *Engine) Run(input string, onChunk func(string)) (string, error) {
    // ... rule matching, LLM call, streaming output ...

    // 4. Record the assistant's response
    runtime.AddHistory("assistant", response)

    // 5. Memory extraction (every N turns, synchronous)
    e.processMemories()   // ← user has finished reading the response by now

    return response, nil
}

processMemories() internal flow:

Extraction interval check: ShouldExtract — triggers when turn_count % 5 == 0 (ExtractInterval = 5)
Call LLM for extraction: takes the most recent 10 turns (ExtractWindow = 10), generates key-event summaries (each no more than 20 words)
Semantic deduplication: shared.DeduplicateMemories uses keyword Jaccard similarity for deduplication — semantically similar memories with different wording are automatically merged. For example: "Faust meets Mephistopheles in his study" and "Mephistopheles visits Faust's study late at night" — both memories share keywords like Faust, Mephistopheles, and study, so they're judged to describe the same event and merged into one
Append + compress: when the count exceeds the limit (MaxLimit = 30), auto-compress — keep the most recent 5 entries plus 3-5 summary entries

Why this design?

User-unaware: streaming is already complete, the user is reading or thinking about the response. Memory extraction happens silently in the background — the user doesn't "wait"
Simple logic: synchronous calls are easier to control than async goroutines — no race conditions, no "memory isn't written yet when saving"

If extraction fails, it only logs silently (the extraction function returns an error and skips it). The conversation continues — just without saving memories for that turn.

VI. The Complete Loop

Putting it all together, here's how each turn of the engine runs:

User input
    │
    ▼
Rule matching
    │   ├── Passive rules (state modification + memory injection): batch execution, multiple can trigger
    │   └── Active rules (LLM instruction / static text): mutually exclusive, only the first match triggers
    │
    ▼
Execute action → LLM call (60-second timeout protection, falls back to ⚠️ static response on failure)
    │                        ↑—— timeout only protects the LLM call phase
    ▼
Streaming output (full-width indentation + chunk-by-chunk callbacks)
    │
    ▼
Record assistant history → (sync) memory extraction (every 5 turns, no streaming wait)
    │
    ▼
Session layer calls Save → auto-save to child file (story.child.meph)
    │
    ▼
Rule hot-reload listener (background async fsnotify, doesn't block main loop)
    │
    ▼
Wait for next input

A few runtime robustness details worth calling out:

LLM timeout fallback: the entire LLM call is wrapped in a 60-second timeout context (context.WithTimeout). On timeout or failure, the engine outputs (⚠️ LLM call failed: request timeout, fallback to static response) via onChunk, then returns a default static text. Telling the user "LLM is down" is better than making them guess "the character went silent" — the former is a diagnosable engineering issue, the latter might be misinterpreted as narrative design.
Debugging and quiet mode: debug output (--debug) goes to os.Stderr, while normal output (--quiet) doesn't interfere. Both can be enabled simultaneously.

This is Mephisto's runtime.

VII. Costs and Limitations

This system doesn't come without cost:

1. Memory extraction depends on LLM quality

If the main model is in poor state, extracted summaries may drift — even altering key facts (e.g., writing "banished" instead of "defeated"). This is a "hallucination" risk.

Two layers of mitigation:

Prompt protection: extraction and compression prompts explicitly forbid modifying core character settings (name, anchor content, state values, etc.). This works reliably on DeepSeek and GPT-4.
Model selection advice: for 7B local models, summary quality drops significantly. If you must use a lightweight model, consider disabling automatic memory extraction (ExtractInterval = 0) and managing memories manually.

Future enhancement: post-extraction validation — after extraction results return, the engine checks for conflicts with core settings. If a conflict is found, discard that memory entry.

2. Branch switching requires manual management

Child files are stored independently. Switching branches requires the user to explicitly specify --branch. Unlike real version control with diff and merge, branches don't auto-sync.

3. Streaming output occupies the terminal

Full-width indentation and streaming look great in the terminal, but if the user wants to copy-paste text, the indentation and newlines come along — sometimes interfering.

VIII. Summary

Six posts complete a full path:

Post	Problem Solved	Core Output
1	What format to write rules in?	`.meph` format design
2	What to run first?	Write a Faust contract from scratch and run it
3	How to parse precisely with good errors?	Block scanner + Parser
4	How to parse rules and variables?	Rule expressions + interpolation syntax
5	How to ensure changes don't break things?	Golden file testing
6	How to bring a contract to life?	Five-layer prompt + branching + memory extraction

Together, they form a complete long-form narrative engine:

Contract (.meph)
    │
    ▼
Parser (Posts 3 & 4) ──→ Contract
    │
    ▼
Engine (Post 6) ──→ Rule matching + LLM streaming narrative + memory extraction
    │
    ▼
Child save (story.child.meph) ──→ Long-term continuity + multiple branches

Quick Reference: Complete Flow

.meph contract file
    │
    ▼ Scanner (line number binding)
    │
    ▼ Block list []Block
    │
    ▼ Parser (routing by block title)
    │
    ▼ domain.Contract
    │   ├─ RoleName
    │   ├─ Anchor
    │   ├─ State
    │   ├─ Worldview
    │   └─ Rules (conditions stored as-is, evaluated at runtime)
    │
    ▼ Engine
    │   ├─ Five-layer sandwich prompt (top constraints → worldview → character → state/history/memory → bottom constraints)
    │   ├─ Rule matching (passive batch + active mutex)
    │   ├─ Action execution (inject / state modify / LLM call / static text)
    │   ├─ Streaming output (full-width indentation)
    │   ├─ Memory extraction (every 5 turns, synchronous, semantic deduplication)
    │   ├─ LLM timeout fallback (60s, ⚠️ message + static response)
    │   └─ Child save (story.child.meph, dot-separated naming)
    │
    ▼ Engine loop
        User input → rule matching → execute action → LLM streaming narrative
        → memory extraction → Session auto-save → hot-reload listener → wait for next input

For quick reference on where to find specific content:

Flow Node	Corresponding Post	Key Concepts
`.meph` format	Post 1	Block titles, rule syntax
Hands-on	Post 2	Write a contract from scratch, no-LLM mode
Scanner	Post 3	Line number binding, whitelist-first
Parser	Post 4	Rule decomposition, interpolation syntax
Testing	Post 5	Golden file, error-scenario tests
Engine runtime	Post 6	Five-layer prompt, branching, memory extraction

GitHub: https://github.com/yuelinghuashu/mephisto

LLM Narrative Engines, Part 5: Integration Testing and Behavior Freezing

yuelinghuashu — Sun, 02 Aug 2026 06:16:48 +0000

Before reading this: I'd recommend skimming Part 3's "Parser" section and Part 4's summary to understand how the parser outputs a domain.Contract. This post assumes you already know the parser can turn .meph into a struct.

I. A Narrative Engine's Fourth Problem: How Do You Keep Behavior Stable?

The parser is written. But it's code that gets maintained long-term — requirements change, formats expand, bugs get fixed. Every change risks breaking existing behavior.

The tension here is: creators depend on stable behavior, while developers depend on freedom to change. If every code change requires manually testing every known scenario, the developer will fear refactoring. If you don't test, broken behavior reaches the creator — but the creator doesn't care that you refactored the parser.

The solution is to "freeze" parsing behavior: use a fixed set of contracts as watchdogs. After every change, automatically compare parse results against expectations.

This is what integration tests do: take a fixed set of .meph contracts as "watchdogs," run them after every change, and verify that behavior hasn't been accidentally altered.

II. Golden File Testing: Freezing Parse Results

The most straightforward approach: prepare a standard contract, parse it, serialize the result to JSON, and save it. On every subsequent test run, compare the current parse result against that JSON file.

The project's testdata/sample.meph is that standard contract. Here's the test flow:

func TestParseSample(t *testing.T) {
    got, err := ParseFile("testdata/sample.meph")
    if err != nil {
        t.Fatalf("parse failed: %v", err)
    }

    goldenPath := "testdata/sample.golden"
    var want domain.Contract

    if err := loadGolden(goldenPath, &want); err != nil {
        // Golden file doesn't exist — generate it automatically
        saveGolden(goldenPath, got)
        t.Log("Golden file generated. Please review and re-run the test.")
        t.FailNow()
    }

    // Compare got and want
    if diff := cmp.Diff(want, got); diff != "" {
        t.Errorf("Parse result doesn't match expected:\n%s", diff)
        t.Log("💡 If this change is intentional, run: go test -update")
    }
}

On first run, sample.golden is auto-generated. Every subsequent run compares against it, reporting differences. If the change is intended (e.g., a new field was added), running go test -update refreshes the Golden file.

The core value of this mechanism: the parser's behavior is "frozen." Any change must pass test validation — it can't silently alter parse results.

III. Parse-Time Validation

Parsing isn't just "reading text in" — it validates required fields during the parse itself.

If the character name is empty, parseRoleName errors out immediately:

Line X: character name cannot be empty

If a rule name, condition, or action is empty, parseRuleLine errors out with the line number.

If parsing fails, the struct doesn't exist. There's no state where "parsing succeeded but content is invalid" — this is another advantage of the hand-written parser over JSON/YAML. JSON parsers don't validate semantic completeness — they only validate structural correctness.

IV. Sliding-Window Aging Tests: Correct History Truncation

The engine has a critical behavior: history can't grow indefinitely. It must auto-truncate, keeping only the most recent N turns.

This test verifies that behavior:

func TestIntegrationHistoryLimit(t *testing.T) {
    contract, err := parser.ParseFile("../parser/testdata/sample.meph")
    if err != nil {
        t.Fatalf("parse failed: %v", err)
    }
    // Set max history to 2 turns
    eng := engine.New(contract, engine.WithMaxHistory(2))

    // Run 5 turns
    for range 5 {
        eng.Run("Hello", nil)
    }

    history := eng.History()
    // 5 turns produce 10 records, but capacity is only 4 (2 turns * 2 records/turn)
    if len(history) != 4 {
        t.Errorf("history length = %d, want 4", len(history))
    }
}

This test ensures history truncation is "whole-turn" rather than "per-record." If truncation were per-record, you could end up with only the "fate" input and no "assistant" response — half a turn of data, leading to incomplete context in the 【命运的推动】 prompt block.

Whole-turn truncation preserves history integrity — either a full turn (fate + assistant) is retained, or it's discarded entirely.

V. Error Scenario Testing: Ensuring Precise Error Messages

Beyond the "happy path," integration tests cover the error path — ensuring all kinds of malformed input produce correct errors, with line numbers and block names included:

func TestParseErrors(t *testing.T) {
    tests := []struct {
        name    string
        input   string
        wantErr string // substring the error should contain
    }{
        {
            name:    "content outside any block",
            input:   "content outside any block\n【角色名】\nBelial",
            wantErr: "content appears outside any block",
        },
        {
            name:    "list item missing - prefix",
            input:   "【锚点】\n核心信念: power",
            wantErr: "list item must start with '-'",
        },
        {
            name:    "list item missing colon",
            input:   "【锚点】\n- 核心信念 \"power\"",
            wantErr: "missing ':' or '：'",
        },
        // ...
    }

    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            _, err := ParseString(tt.input)
            if err == nil || !strings.Contains(err.Error(), tt.wantErr) {
                t.Errorf("expected error containing '%s', got: %v", tt.wantErr, err)
            }
        })
    }
}

These tests ensure error messages never degrade to unexpected token at position 42 — the kind of error we set out to eliminate in Part 1.

VI. The Cost

Golden files need manual review on first generation or update (checking that the content is correct)
Error-scenario tests need to cover as many edge cases as possible
Each new block type requires updating test cases

But the payoff is: you can refactor fearlessly. As long as all tests pass, behavior hasn't changed.

VII. Summary

Integration tests are the project's "watchdogs." They freeze the parser's behavior, and every change must pass their validation.

Four things make up this test suite:

Golden file tests: freeze the parse results of a standard contract
Parse-time validation: check required fields and completeness during parsing
Sliding-window aging tests: ensure history is truncated by whole turns
Error-scenario tests: guarantee error messages are precise down to the line number

With this system in place, the engine can evolve confidently — no fear of breaking things, because the tests will catch it.

Next, we enter the engine's runtime. The core problem: once you have a domain.Contract, how do you drive the LLM to generate narrative that follows the rules?

The answer is the sandwich prompt structure — putting format constraints at both the top and bottom, with context in the middle — to completely eliminate parenthetical stage-direction drivel.

GitHub: https://github.com/yuelinghuashu/mephisto

LLM Narrative Engines, Part 4: Parsing Rules and Interpolation

yuelinghuashu — Wed, 29 Jul 2026 03:48:48 +0000

Before reading this: I'd recommend skimming Part 3's "Two-Phase Design" and "Block Scanner" sections to understand how the scanner outputs []Block. This post assumes you already know how the parser routes blocks to different parse functions based on their Title.

I. A Narrative Engine's Third Problem: How Do You Parse Condition-Action Rules?

Once the blocks are split, the most complex part is rule expressions. A narrative engine needs to answer: how are conditions written, how are actions written, and how are variables referenced?

There's an important design boundary here: the parser only parses, it doesn't evaluate. Condition strings like 包含 "攻击" && 状态.堕落指数 > 80 are stored as-is in the struct. The engine evaluates them at runtime. Why? Because the runtime state needed for evaluation doesn't exist at parse time — state values change dynamically during conversation and can't be determined at load time.

This post is about the parsing logic itself.

II. Rule Parsing: Splitting Conditions and Actions

The rule format is fixed: [name] if condition -> action

[攻击] if 包含 "攻击" -> 注入 "贝利亚发动了猛烈的攻击"
[光之国] if 包含 "光之国" && 状态.情绪 == "暴怒" -> 注入 "光之国的记忆让贝利亚更加愤怒"
[高堕落] if 状态.堕落指数 > 80 -> 状态.情绪 = "癫狂"

Interpolation syntax appears in rule actions and text blocks:

注入 "{角色名}的故乡是光之国"

This post tackles two problems:

How do we parse rule conditions and actions into storable structures?
How is interpolation syntax recognized and handled at the parsing layer?

2.1 Rule Name Extraction

Find the first [ and the first ], extract what's between them:

func parseRuleLine(line string, lineNumber int) (*domain.Rule, error) {
    trimmed := strings.TrimSpace(line)
    if !strings.HasPrefix(trimmed, "[") {
        return nil, fmt.Errorf("规则必须以 '[' 开头")
    }
    idx := strings.Index(trimmed, "]")
    if idx == -1 {
        return nil, fmt.Errorf("缺少闭合的 ']'")
    }
    name := strings.TrimSpace(trimmed[1:idx])
    if name == "" {
        return nil, fmt.Errorf("规则名不能为空")
    }

    rest := strings.TrimSpace(trimmed[idx+1:])
    // Extract condition and action next...
}

Note: The error messages in the Go code above are shown in Chinese — they're the actual output from the engine's parser.

2.2 Splitting Condition and Action

Use if and -> as delimiters:

// Remove the "if " prefix
if !strings.HasPrefix(rest, "if ") {
    return nil, fmt.Errorf("规则条件必须以 'if ' 开头")
}
rest = strings.TrimPrefix(rest, "if")
rest = strings.TrimSpace(rest)

// Use the first "->" to split condition and action
cond, action, ok := strings.Cut(rest, "->")
if !ok {
    return nil, fmt.Errorf("规则缺少 '->'")
}
cond = strings.TrimSpace(cond)
action = strings.TrimSpace(action)

2.3 Mutex Groups

Actions may contain a [group:xxx] marker:

[攻击] if 包含 "攻击" -> [group:combat] 注入 "贝利亚发动了猛烈的攻击"

When parsing, we extract the group name and store it in domain.Rule.Group:

group := ""
if strings.HasPrefix(action, "[group:") {
    endIdx := strings.Index(action, "]")
    if endIdx != -1 {
        group = action[7:endIdx]
        action = strings.TrimSpace(action[endIdx+1:])
    }
}

Mutex groups ensure that within the same group, only the first matching rule is triggered. This logic takes effect at runtime; the parser just stores the group name.

Mutex groups can be used with any action type, not just 注入:

[高堕落] if 状态.堕落指数 > 80 -> [group:escalate] 状态.情绪 = "癫狂"
[失控] if 状态.情绪 == "癫狂" && 状态.堕落指数 > 90 -> [group:escalate] 注入 "{角色名}已完全失控"

2.4 Quote Handling

Strings in conditions and actions are wrapped in ". During parsing, I call unquote to strip the outer quotes:

func unquote(s string) (string, error) {
    s = strings.TrimSpace(s)
    if len(s) >= 2 {
        if (strings.HasPrefix(s, "\"") && strings.HasSuffix(s, "\"")) ||
           (strings.HasPrefix(s, "“") && strings.HasSuffix(s, "”")) {
            return s[1:len(s)-1], nil
        }
    }
    return s, nil
}

Chinese quotes are supported because creators may use Chinese input methods — “ and ” are more natural to type than ".

III. Interpolation Syntax: Recognizing and Replacing `{variable}`

The core requirement for interpolation: recognize {角色名} in any text and replace it with the corresponding character name. Currently, only one interpolation variable is supported — {角色名}, which comes from the 【角色名】 block and is statically defined.

3.1 Why Only `{角色名}`?

You might wonder: why can't state variables like corruption index or emotion be interpolated directly with {堕落指数}?

Because state variables are read and written dynamically at runtime — creators modify them via 状态.键 = 值 and compare them via 状态.键 > 值. Allowing {堕落指数} interpolation would introduce a parallel mechanism: the same variable could be referenced both via 状态.堕落指数 and {堕落指数}. Two syntaxes for the same thing, increasing the learning curve.

So state variables are uniformly referenced using the 状态.键 syntax, with no interpolation. The engine's template substitution does one thing only: replace {角色名} with the actual character name.

3.2 Substitution Timing: Three Scenarios

Interpolation substitution happens in three different scenarios:

CLI welcome screen display: Worldview and opening scenes are substituted once when displayed to the user. The creator sees "贝利亚奥特曼" instead of {角色名}.
Rule action execution: 注入 "{角色名}的故乡是光之国" is substituted every time the rule triggers. This is the most common usage of interpolation.
Prompt construction: Worldview and background text are passed to the LLM as-is, without engine-side substitution. The LLM naturally understands {角色名} from context (e.g., "You are 贝利亚奥特曼").

Why not substitute in scenario 3?

Because substitution changes the raw form of the text. If we replace {角色名}的故乡是光之国 with 贝利亚奥特曼的故乡是光之国, the LLM receives a "hardened" narrative. Keeping {角色名} as-is lets the LLM dynamically decide how to use the name during generation — in some narrative branches, the character name might change (e.g., the character is renamed or forgotten), and keeping the placeholder is actually more flexible.

IV. The Intersection: When Rules Meet Interpolation

Take this rule as an example:

[光之国] if 包含 "光之国" -> 注入 "{角色名}的故乡是光之国"

Full execution flow:

User input: "I'm going to the Land of Light!"
    │
    ▼
Rule matching: contains "光之国" → true
    │
    ▼
Action recognition: action type is "注入"
    │
    ▼
Runtime substitution: {角色名} → "贝利亚奥特曼"
    │
    ▼
Append to memory: "贝利亚奥特曼的故乡是光之国" written to memory
    │
    ▼
LLM narrative: generates response with the new memory

Why is substitution done at runtime?

Because the engine supports multiple branching storylines. If substitution happened at load time, all branches would share the same static value and couldn't evolve independently. Runtime substitution means each branch reads its own state — when the state changes, the interpolation result changes with it.

Dice Expression Error Tolerance

Dice expressions like roll(1d100) >= 80 are stored as-is during parsing and evaluated at runtime. If the expression has a format error — e.g., roll(1d10 missing a closing parenthesis — the engine doesn't report an error. Instead, it treats the condition as not satisfied (returns false). This is because dice expressions are part of conditions, and the parsing layer isn't responsible for validating runtime correctness — malformed expressions are simply treated as "no match."

V. Summary: The Parsing Layer Is Complete

At this point, the parsing layer covers all syntax units:

Block Type	Parse Function	Complexity	Notes
Text blocks	`parseTextBlock`	Low	Concatenates content, preserves newlines
Key-value lists	`parseKeyValuePairs`	Medium	Supports Chinese/English colons, precise error reporting
Rule lists	`parseRules`	High	Condition expressions, mutex groups, dice expressions
Plain text lists	`parsePlainList`	Low	Extracts lines one by one
Interpolation	`ReplacePlaceholders` (runtime)	Medium	Preserved at parse time, substituted at runtime

The most critical boundary:

The parser only "reads" — it turns text into structured data.
The engine "computes" — condition evaluation, variable substitution, action execution.

Next, we cross that boundary and enter the engine's runtime. The first engineering challenge the engine faces: how do we ensure code changes don't break existing parsing behavior?

The answer is integration testing — using a fixed set of .meph contracts as "watchdogs," comparing parse results against expectations after every change.

GitHub: https://github.com/yuelinghuashu/mephisto

LLM Narrative Engines, Part 3: Block Scanner and Line Numbers

yuelinghuashu — Sat, 25 Jul 2026 07:56:12 +0000

Before reading this: If you jumped here from a search engine, I'd recommend skimming Part 1's "See the Target" and ".meph Design Principles" sections to get familiar with what .meph looks like and why it exists. This post assumes you already know what 【角色名】 and 【规则】 are.

A JSON parser reports position 246. What a creator needs is "line 12: missing colon." This post is about making that precise error reporting a reality.

I. A Narrative Engine's Second Problem: How Do Rules Become Structure?

Once the format is defined, the next problem is parsing — how do we turn text into data the program can work with?

Two metrics matter here: parsing correctness and error readability. General-purpose formats (JSON/YAML) excel at the first but are a disaster on the second — position 246 means nothing to a creator. And for a custom format, the parser must be written from scratch.

A well-designed parser should do three things:

Precise recognition — every block and every line must be correctly classified
Line number binding — every error must trace back to a specific line, not a byte offset
Whitelist validation — typos like 【脚色名】 (a misspelling of "Character Name") should not be silently treated as valid content

This post implements all three.

II. See the Problem First: What Happens Without Line Numbers

Before diving into the parser, let's look at a real scenario.

A creator writes a contract with this line:

【锚点】
- 核心信念 "力量就是一切"

Notice: - 核心信念 "力量就是一切" is missing a colon. The correct form is - 核心信念: "力量就是一切".

With a general-purpose parser, the error would be something like:

unexpected token at position 42

The creator has to copy-paste and count characters to figure out where position 42 is. This process is excruciating.

My goal was to make the parser report:

第 2 行（区块「锚点」）：缺少 ':' 或 '：'

No counting positions, no understanding what a "token" is — just "line 2, block '锚点': missing ':'."

This difference is the entire reason for writing a custom parser.

III. Two-Phase Design

I split the parsing into two phases:

Phase	Responsibility	Input	Output
Block Scanner (Lexer)	Split into blocks, record line numbers	Raw text	`[]Block`
Structured Parser	Parse into structured data	`[]Block`	`*domain.Contract`

Key design decision: line numbers are bound during the scan phase. The parser receives them pre-attached and never needs to calculate offsets. This means error reporting always has precise, absolute line numbers.

Two data structures:

type Line struct {
    Text   string
    Number int  // absolute line number, starting from 1
}

type Block struct {
    Title   string  // e.g., "角色名"
    Content []Line  // content lines with their line numbers attached
    Line    int     // the line number of the title line
}

With this structure, error reporting becomes straightforward:

fmt.Errorf("第 %d 行（区块「%s」）：列表项必须以 '-' 开头",
    line.Number, blockName)

IV. Block Scanner: A Simple State Machine

The core is a line-by-line state machine. It has only two states:

inBlock == false: currently outside any block
inBlock == true: inside a block, collecting content

func Lex(text string) ([]Block, error) {
    lines := strings.Split(text, "\n")
    var blocks []Block
    var currentTitle string
    var currentContent []Line
    var currentLine int
    inBlock := false

    for i, rawLine := range lines {
        lineNumber := i + 1

        // Outside a block: skip empty lines
        if !inBlock && strings.TrimSpace(rawLine) == "" {
            continue
        }

        // Check if this line is a block title
        if title, ok := isBlockTitle(rawLine); ok {
            if inBlock {
                // Save the current block
                blocks = append(blocks, Block{
                    Title:   currentTitle,
                    Content: currentContent,
                    Line:    currentLine,
                })
            }
            // Start a new block
            currentTitle = title
            currentContent = []Line{}
            currentLine = lineNumber
            inBlock = true
            continue
        }

        // Non-title line: must be inside a block
        if !inBlock {
            return nil, fmt.Errorf("第 %d 行：内容出现在任何区块之外", lineNumber)
        }

        currentContent = append(currentContent, Line{
            Text:   rawLine,
            Number: lineNumber,
        })
    }

    if inBlock {
        blocks = append(blocks, Block{...})
    }

    if len(blocks) == 0 {
        return nil, fmt.Errorf("没有有效区块")
    }
    return blocks, nil
}

Two key design decisions:

1. Whitelist first

isBlockTitle only recognizes a predefined set of titles:

var knownBlocks = map[string]bool{
    "角色名": true,
    "锚点":  true,
    "规则":  true,
    "状态":  true,
    // ...
}

If a creator writes 【脚色名】 (a typo), the scanner won't treat it as a block start — it will return an error pointing to that line. The exact error message depends on context: if the line appears outside any block, it's "content appears outside any block"; if it appears inside a block, the block's parser will catch it. Either way, the line number is precise.

2. Line number binding

Every line carries its lineNumber at storage time, never offset. This is the foundation of precise error reporting.

V. Parser: Routing to Different Parse Functions

After the scanner outputs []Block, the parser routes each block to its corresponding parse function based on Title:

func parseBlocks(blocks []Block) (*domain.Contract, error) {
    contract := &domain.Contract{}
    for _, block := range blocks {
        switch block.Title {
        case "角色名":
            contract.RoleName, err = parseRoleName(block.Content, block.Line)
        case "锚点":
            contract.Anchor, err = parseKeyValuePairs(block.Content, block.Title)
        case "规则":
            contract.Rules, err = parseRules(block.Content, block.Title)
        // ... other block types
        }
        if err != nil {
            return nil, err
        }
    }
    return contract, nil
}

Each block type has its own parsing logic. Here's the key-value parser — note that every error includes the line number and block name:

func parseKeyValuePairs(lines []Line, blockName string) ([]KeyValue, error) {
    for _, line := range lines {
        trimmed := strings.TrimSpace(line.Text)
        if trimmed == "" || strings.HasPrefix(trimmed, "#") {
            continue
        }
        if !strings.HasPrefix(trimmed, "-") {
            return nil, fmt.Errorf("第 %d 行（区块「%s」）：列表项必须以 '-' 开头",
                line.Number, blockName)
        }
        // ... extract key-value pair
    }
    return result, nil
}

VI. Error Message Comparison

Same error, two experiences:

What the user wrote wrong	Generic parser error	`.meph` parser error
`- 核心信念 "力量"` (missing colon)	`Unexpected token at position 42`	`第 2 行（区块「锚点」）：缺少 ':' 或 '：'`
`情绪: 暴怒` (missing `-`)	`invalid character looking for value`	`第 2 行（区块「状态」）：列表项必须以 '-' 开头`
`【脚色名】` (typo)	N/A	Points to the exact line with an error

VII. The Cost

Approximately 400 lines of Go code
Need to write independent parsing logic for each block type
Adding a new block type means updating the whitelist

But there are no external dependencies. go build completes in one step. The parsing logic is fully controllable and can be adjusted at any time.

VIII. Summary

The block scanner and parser complete the "text to structure" transformation. 【角色名】 is now contract.RoleName. 【规则】 is now contract.Rules.

But the conditions in contract.Rules — like 包含 "攻击" — and the actions — like 注入 "{角色名}的故乡是光之国" — are still strings. The next post tackles: how do we parse rule condition-action expressions? How does the {变量} interpolation syntax work?

Those are the last two pieces of the parsing layer.

GitHub: https://github.com/yuelinghuashu/mephisto

LLM Narrative Engines, Part 2: Quick Start — Write Your First Contract

yuelinghuashu — Thu, 23 Jul 2026 13:13:17 +0000

Before reading this: If you haven't read the first post, From Freeform to Constrained Generation, I'd recommend starting there to understand why .meph exists. This post requires zero prior knowledge — just a terminal and Go 1.26+.

In the previous post, we talked about why .meph is a better fit for narrative contracts than JSON or YAML. But talk is cheap.

Then let's stop talking and start building. We'll write a real contract from scratch, compile it, and run it. You'll have your first narrative running in no time — and you'll see, firsthand, how the rules you write drive LLM-generated storytelling.

I. What You'll Need

Three things:

Go 1.26+ — open a terminal and run go version to check
A terminal — any OS works
(Optional) An LLM API key — DeepSeek, OpenAI, or Ollama all work. Not required — the engine runs fine without an LLM.

If you have an API key, create a .env file in the project root:

MEPHISTO_CLIENT=openai
MEPHISTO_MODEL=deepseek-v4-flash
OPENAI_API_KEY=sk-your-key-here

II. Clone and Build

git clone https://github.com/yuelinghuashu/mephisto.git
cd mephisto
go build -o ./mephisto ./cmd/mephisto

If everything goes well, you'll see a binary named mephisto.

III. Write Your First Contract

Now for the real work. Create a new file data/faust.meph and fill it from scratch.

3.1 Character Name

The first line of any contract is the character name. Mark the block with 【角色名】 (Character Name) and write the name directly below:

【角色名】
Faust

That's it — no quotes, no colons, no markup.

3.2 Anchor

The 【锚点】 (Anchor) block defines the character's core personality. Use the - key: value format:

【锚点】
- 核心信念：Knowledge above all else. I would pay any price for truth.
- 欲望：To experience everything a human can experience.
- 绝对禁忌：I will never admit regret.

These are injected directly into the LLM's context — they're the bedrock of the character's behavior.

3.3 State

【状态】 (State) holds dynamic variables, also in key-value format:

【状态】
- 灵魂完整度：100
- 情绪：Never satisfied
- 位置：Study

State values support three types: numbers, booleans, and strings. The engine infers types automatically at parse time — "100" becomes the number 100, while "Never satisfied" stays a string. This means you can write conditions like 状态.灵魂完整度 > 50 directly, without manual type conversion.

At runtime, state is stored as a map[string]any for fast read/write. Initial order is inherited from the contract, but runtime access is key-based and order-agnostic.

3.4 Worldview

【世界观】 (Worldview) is multi-line text. Write freely — line breaks are preserved:

【世界观】
The story takes place in 16th-century Germany, an era where theology and science are locked in tension. Universities are consumed by sterile scholastic debates; real knowledge is suppressed. The world is composed of God, angels, demons, and mortals — Heaven and Hell are real dimensions. Mephistopheles is a hellish emissary, skilled at trapping souls through words and contracts. Soul transactions are legally binding in this world — once a soul contract is signed, there's no revocation.

3.5 Character Background

【角色背景】 (Character Background) works alongside Worldview to define the character's history:

【角色背景】
Faust is a scholar of vast learning — philosophy, medicine, law, and theology. Yet he despairs at the limits of human knowledge: after a lifetime of study, he still cannot touch the essence of the world. In his despair, he signs a contract with Mephistopheles: his soul in exchange for unlimited earthly experience.

3.6 Opening Scene

【开局场景】 (Opening Scene) sets the stage when the conversation begins:

【开局场景】
Late night. Candlelight flickers in the study, books piled high on the desk. Faust stands by the window, gazing at the moonlight. On the corner of the table lies a contract, its ink still wet.

3.7 Rules — The Heart That Brings the Character to Life

【规则】 (Rules) is the engine's core. Each rule has three parts: [name] if condition -> action.

【规则】
[New Desire] if 包含 "追求" || 包含 "想要" || 包含 "体验" -> 注入 "{角色名} feels a new longing kindle in his chest — nothing can stop him from experiencing it all firsthand"
[Mephistopheles] if 包含 "梅菲斯特" || 包含 "契约" -> 注入 "Mephistopheles's voice whispers at {角色名}'s ear: 'Is this what you truly want? Have you considered the price?'"
[Soul's Price] if 包含 "代价" || 包含 "灵魂" -> 注入 "{角色名} looks down at his hands, as if he can see something slowly slipping away"
[Never Satisfied] if 不包含 "放弃" && 不包含 "满足" -> 注入 "{角色名}'s eyes burn with an unquenchable flame — he still wants more"

Rule conditions support logical operators (&&, ||), state comparisons (状态.key > value), and dice expressions (roll(1d100)). The most common action is 注入 (inject) — it appends a message to memory, which the LLM then weaves naturally into the ongoing narrative.

3.8 Validate

Save the file and validate the parse:

./mephisto parse data/faust.meph

You'll see JSON output like this:

{
  "role_name": "Faust",
  "anchor": [...],
  "state": [...],
  "rules": [...]
}

If parsing fails, the error tells you exactly what's wrong and where — something like "line 12 (block '锚点'): missing ':' or '：'."

IV. First Conversation (No LLM Mode)

The engine runs fine even without an LLM:

./mephisto run data/faust.meph

You'll see a welcome message, then enter the conversation loop. Type "I want to experience love":

命运 > I want to experience love
Faust gazes silently at fate.

No LLM means the engine returns the default response. But rules still fired — the input contained “想要” (want), which matched the condition 包含 "想要", triggering the [New Desire] rule and writing the injection into memory.

Type /state to see the current state:

Current state:
  灵魂完整度: 100
  情绪: Never satisfied
  位置: Study

Type /history to see the conversation log — your input “I want to experience love” is already recorded as a fate directive.

This is how the engine works without an LLM: rule matching, injection, state management — everything runs normally. The LLM is just the final “narrative rendering layer.”

V. Bring in the LLM

Now add your API key and run again:

./mephisto run data/faust.meph -debug

You'll see the same welcome message, this time with -debug enabled. The LLM configuration will be displayed first.

Then type this at the prompt:

命运 > You want to acquire knowledge beyond human comprehension

The terminal shows debug output — and then Mephistopheles steps out of the shadows:

🔍 Rule debug mode
----------------------------------------
📌 Checking rule [New Desire] (line 26)
   Condition: 包含 "追求" || 包含 "想要" || 包含 "体验"
   Result: true
   ✅ Triggered → inject "{角色名} feels a new longing kindle in his chest, no...

  The candlelight in the study flickered, casting the parchment rolls and codices that lined the walls into shifting pools of light and shadow. Faust sat slumped at his desk, piled high with manuscripts, his fingertips tracing the worn cover of an old astronomy text. But his gaze drifted past the window, into the pitch-black night. He muttered, his voice hoarse, almost carried away by the draft: “A lifetime of searching, and I've never even pushed open a single door.”

  Then, from the bookshelves behind him, came a sound — soft, like a mouse gnawing at wood, or a stifled chuckle. Faust did not turn. He said coldly: “Is that you again, Wagner? It's late. You needn't bring me any more warm broth.”

  But the footsteps were light — too light for his clumsy apprentice. A low, metallic voice emerged from the darkness: “Wagner is only fit to stoke your fire. I bring a different kind of warmth.” A figure stepped out of the shadows — tall, draped in a sumptuous crimson robe, with a lean face and a smile that seemed to curve just slightly too far. He toyed with a bronze ring between his fingers. He stopped before the desk, leaned forward slightly, and fixed his gaze on Faust's eyes: “You said a moment ago that you've spent your life unable to push open that door. But have you ever considered that doors weren't meant to be pushed?”

  Faust slowly lifted his head and fixed his stare on this uninvited guest. His hand pressed flat on the astronomy text. “Who are you? You enter my study without permission.”

  The man gave a soft laugh and turned the ring in the candlelight. It cast a twisted shadow — as though it were some kind of unutterable sigil. “I am the answer to all your questions — and the price of all your desires.” He extended his hand, palm up, fingers spread. Dim red light pulsed through the lines of his palm. “I can show you the patterns behind the stars. I can let you hear the melody that played at the beginning of creation. I can let you touch the law itself. All I ask in return is one small, insignificant thing.”

  Faust rose to his feet, his sleeve sweeping across the scattered drafts on the desk. Sheets of formulae and notes drifted to the floor. He stared at that outstretched hand for a long time, then finally spoke: “What do you want?”

  The man's smile widened, his voice soft as a feather brushing a blade: “Your soul. But don't worry — you don't use it anyway. It can't solve your equations. It can't carry you to the heavens. Keeping it is just letting it rot with a body that's already decaying.” He withdrew his hand and instead produced a roll of jet-black parchment, which he unfurled across the desk. The surface held no script, only an abyss of darkness that seemed to swallow the light around it. “Sign it, and I will deliver everything at once.”

  Faust's breath quickened. He looked down at that dark expanse, then up at the man's eyes — which reflected the birth and death of countless stars. At last, he reached out. His fingertip touched the parchment, and a chill shot up along his shoulder. He hesitated no longer. He took the quill the man offered, pricked his own thumb, and let the blood fall onto the page.

  Just then, the study door creaked open a crack. Wagner peered in, clutching a dim oil lamp. He saw the stranger in the room, then saw the blood on his master's fingertip. His face went white. Trembling, he cried out: “Master! What are you doing? When did this man enter?”

  Faust didn't stop. The blood-script was already taking form on the parchment. Without turning, he said: “Wagner, close the door. Tonight you will witness a scholar's final wish.” As the words faded, the darkness on the parchment began to churn, spreading through the room like a starless night unfurling — while the crimson-robed man's laughter echoed among the scrolls.

That's what those 30 lines of contract you just wrote can generate.

Now try changing just one number.

Open data/faust.meph, change 灵魂完整度 in 【状态】 from 100 to 50, save, and run again. Type the same line:

命运 > You want to acquire knowledge beyond human comprehension

Same rules, same input, one number different — and the narrative shifts entirely:

  The candlelight in the study swayed, casting enormous shadows that crawled across the shelves like living things. Faust slumped in his chair behind a mountain of books. A quill hung between his fingers, the ink long dry on its tip. His empty gaze swept across the Latin, Greek, and Hebrew scrolls — these symbols that had once enraptured him now lay like dried insect husks, drained of meaning.

  “Forty years,” he rasped, barely audible. “Forty years of study, and I have not even touched the edge of the first heaven.”

  From outside came the low cry of a night bird, as though something was answering his despair. At that moment, the study door opened silently, and in came his old servant Wagner, carrying a steaming bowl of herbal broth. He picked his way carefully through the scattered parchment, set the bowl on the corner of the desk, and spoke with evident worry: “Master, you haven't eaten for three days. You've been reading Paracelsus all night — your eyes are bloodshot. If you keep this up…”

  “If I keep this up, what? What's the worst that could happen — this body rotting before my desires do?” Faust's head snapped up, a near-crazed light kindling in his eyes. “Wagner, you've studied for years too. Tell me — have you ever seen the face of truth?”

  Wagner stepped back, daunted by the look in Faust's eyes. He murmured: “Master, this servant believes that truth is God's affair.”

  “God's affair.” Faust repeated the words, then burst into laughter — laughter thick with bitterness. “Exactly. Exactly. We hand everything over to God, fencing ourselves in with theological rails, safe in our pigsties, chewing the dry crusts the priests toss us — and we're grateful for it!” He rose to his feet, knocking over his chair behind him. The candle flame almost died under the wind of his robe. “I'm done with these words, these symbols, this stuff written by men to deceive one another. I need real knowledge — the knowledge that belongs to the ancient ones, the primordial ones.”

  Wagner stared at him in terror, his hands trembling. “Master… what are you saying? Such thoughts are blasphemy…”

  “Blasphemy?” Faust strode to the window and threw it open. The cold night wind rushed in, whipping his gray hair and robe into frenzy. “If seeking truth is blasphemy, then let this blasphemy be complete.” He turned, his eyes burning like live coals. “Wagner, leave. Tonight I need to be alone.”

  Wagner opened his mouth, but finally lowered his head and retreated quickly. The wooden door closed heavily behind him. Faust stood alone at the open window, staring up at the star-filled, silent sky. He whispered: “You've been standing there for billions of years. Do you have nothing to say to this mere mortal?”

  No sooner had the words left his mouth than the candle flame on the desk leaped high, turning into a sheet of blue fire. From its center, a voice spoke — low, elegant, not coming through the air, but echoing directly inside Faust's skull.

  “You're finally ready to listen, Mr. Faust.” The voice carried a smile. “Then allow me to introduce myself.”

Notice the difference: at soul integrity 100, Faust is a “contemplative scholar,” calmly skeptical when Mephistopheles appears — “Who are you? Entering my study without permission.” At soul integrity 50, he becomes a “brilliant scholar teetering on the edge of self-destruction,” shouting at Wagner, redefining the pursuit of knowledge as blasphemy. Even Mephistopheles' entrance changes — not emerging from shadow, but erupting from candle flames, his voice resonating directly inside Faust's skull.

A single state value changes, and the entire texture of the narrative transforms. That's the power of state-driven storytelling.

Look closely at the first output:

Faust's identity as a scholar — drawn directly from 核心信念：Knowledge above all else in 【锚点】 and the 【世界观】 line about spending a lifetime without touching the essence of reality. The LLM faithfully inherited these traits.
Mephistopheles's appearance — triggered by the [New Desire] rule from the input “want.” The injected memory gave the LLM the context: “Faust feels a new longing kindle in his chest.”
“Price” and “soul” — the LLM naturally introduced the theme of “price,” which triggered the [Soul's Price] rule — even though you didn't explicitly type those words.
“Never satisfied” as an underlying tone — the [Never Satisfied] rule has the condition 不包含 "放弃" && 不包含 "满足" (doesn't contain “give up” and doesn't contain “satisfied”), which fires on almost every turn. It constantly injects “Faust still wants more,” making this not just a one-turn interaction but a persistent character trait that runs through the entire narrative.

Every rule is doing work. Not a single one is wasted.

VI. Try Changing Something

Now that you've seen the engine in action, make some changes and see what happens:

Change a State Value

- 灵魂完整度：50

You already saw the result. Try 10 or 0 and see how Faust changes.

Add a Dice Rule

[Favor of Fate] if 包含 "追求" && roll(1d100) >= 80 -> 注入 "Fate seems to favor {角色名} — things go more smoothly than expected"

roll(1d100) >= 80 means: roll a 100-sided die, and the rule only triggers if the result is >= 80. A 20% success rate — not every pursuit is lucky. This introduces real randomness into the story.

Run Two Turns, Then Look at the Child Save

After a couple of turns, open data/faust_child.meph in a text editor:

【状态】
- 灵魂完整度：100
- 情绪：Never satisfied

【记忆】
- Faust feels a new longing kindle in his chest…
- Mephistopheles's voice whispers at Faust's ear…

【历史】
- fate: I want to experience love
- assistant: …

This is the engine's Mother-Child save mechanism: faust.meph is the read-only master contract; faust_child.meph is the dynamic snapshot containing runtime state, memories, and history. Automatically saved after every conversation.

VII. Summary

At this point, you've done three things:

Written a complete contract — 30 lines covering character name, anchor, state, worldview, background, opening scene, and rules
Validated its structure with the parser — the parse command tells you precisely whether your contract is correct
Run the engine and watched the character come alive — even without an LLM, rules still fire; with an LLM, every rule you wrote shapes the narrative direction

Those 30 lines are the contract between you and the engine. The engine ensures the LLM honors it.

Next post goes under the hood. It answers one critical question: how does the block scanner precisely recognize 【角色名】 and 【规则】? And why can errors report “line 12, block ‘锚点’: missing ':' or '：'” — instead of unexpected token at position 246?

The answer is a handwritten block scanner — a lightweight lexer that scans line by line, binds precise line numbers, and enforces a block whitelist. See you in the next one.

GitHub: https://github.com/yuelinghuashu/mephisto

LLM Narrative Engines, Part 1: From Freeform to Constrained

yuelinghuashu — Mon, 20 Jul 2026 13:47:44 +0000

On the first day I started building narratives with LLMs, I hit a wall.

I defined a character: Belial, a fallen Ultraman — arrogant, contemptuous of the Land of Light, obsessed with power. The first three turns were perfect. Every response carried that satisfying villainous edge. By the fifth turn, he started giving me life advice, like a mild-mannered philosopher. By the tenth, he called himself "a guardian of the Land of Light." He had completely forgotten who he was.

This isn't a model quality issue. It's the fundamental flaw of free generation — LLMs have no built-in mechanism to "enforce rules." You can write "you are an arrogant villain" in the system prompt, but the model's understanding of "arrogant" is probabilistic. Over long contexts, it attenuates, overwritten by user inputs, model outputs, and even token-order drift.

I needed a way to write down rules that the model must follow. So I started building Mephisto.

But before writing the engine code, I had to solve a more fundamental problem: what format should these rules be written in?

The format needs to carry: the character name (single-line), the worldview (multi-line), state variables (key-value pairs), and behavioral rules (condition-action pairs). Each type has a different structure and parsing strategy. The choice of format determines whether the creator spends their time writing stories or debugging syntax.

This post documents my trade-offs and final decision.

I. A Narrative Engine's First Problem: How Do You Express Rules?

A narrative engine's first problem is the rule expression layer — how does the creator tell the engine what this character will and won't do? There are three common approaches:

General-purpose structured formats (JSON/YAML): program-friendly, but cruel to creators — escaping hell, unreadable error messages
Custom domain-specific formats (like .meph, Ink): a middle ground, but the parser must be written from scratch
Plain text: most friendly to creators, but almost impossible for programs to parse precisely

Each approach has a cost. I'll compare them one by one, then explain why I chose the custom path.

II. See the Destination: A Real .meph Contract

Before discussing any design decisions, let's look at the finished product. Here's a complete .meph contract, taken from the project's data/sample.meph:

【角色名】
贝利亚奥特曼

【锚点】
- 核心信念：力量就是一切
- 说话风格：狂傲、嘲讽、不容置疑

【世界观】
光之国是宇宙中最强大的文明，也是贝利亚的故乡。
但他早已被驱逐，如今他带着对光之国的憎恨归来。

【状态】
- 堕落指数：50
- 情绪：暴怒
- 位置：宇宙空间站

【规则】
[攻击] if 包含 "攻击" -> 注入 "贝利亚发动了猛烈的攻击"
[防御] if 包含 "防御" || 包含 "防守" -> 注入 "贝利亚摆出了防御姿态"
[光之国] if 包含 "光之国" -> 注入 "{角色名}的故乡是光之国，也是他最大的仇恨来源"
[高堕落] if 状态.堕落指数 > 80 -> 状态.情绪 = "癫狂"

This is the entire contract. The creator sees not { and }, not escaped quotes, not indentation levels, but:

A name directly under 【角色名】
Key-value pairs under 【锚点】 using - key: value
Rules under 【规则】 using [name] if condition -> action

Notice {角色名} in the rules — that's interpolation syntax. The parser stores it as-is, and the engine replaces it at runtime with the current character name. This ensures branches evolve independently without interfering with each other.

It reads like a document. But the program can parse it precisely, and when something goes wrong, it can tell the creator "line 12, block '状态': list item must start with '-'" — not unexpected token at position 246.

The question is: how did I get here?

III. JSON: Friendly to Programs, Hostile to People

JSON was the obvious first choice. Clean structure, simple parsing, mature libraries in every language. I actually built a prototype with JSON — I still have that yellowed printout somewhere, covered in handwritten notes. Then I hit the fatal problem.

That rule from above, in JSON:

{
  "rules": [
    {
      "name": "攻击",
      "condition": "包含 \"攻击\"",
      "action": "注入 \"贝利亚发动了猛烈的攻击\""
    }
  ]
}

The creator's intent:

包含 "攻击"

In JSON, it becomes:

"condition": "包含 \"攻击\""

The problem isn't that the syntax is "hard." It's context switching cost.

The creator can't directly express their intent — they have to constantly think "am I writing JSON or am I writing rules?" Over a large contract, this cost accumulates. You're not reading content; you're constantly verifying how many backslashes are on this line.

Even worse: error messages. A common mistake — a trailing comma after the last element in a JSON array. The JSON parser reports:

Unexpected token } in JSON at position 246

The creator has to paste it into an online tool and count characters to figure out where position 246 is. For non-technical users, this experience is devastating.

JSON is friendly to programs, but hostile to people. And the author of this file is a creator, not a programmer.

IV. YAML: The Mirage of Simplicity

YAML seemed to fix JSON's readability problem:

role_name: 贝利亚奥特曼
rules:
  - name: 攻击
    condition: 包含 "攻击"
    action: 注入 "贝利亚发动了猛烈的攻击"

Indentation replaced brackets and commas. It looked more like "writing a document."

But YAML's problems are more insidious than JSON's. They're not syntax errors — they're logic errors. The file parses, but the behavior is wrong.

Imagine defining a multi-line text block in YAML (a worldview, for example), using the | marker:

worldview: |
  光之国是宇宙中最强大的文明。
  贝利亚被驱逐后，一直在寻找复仇的机会。

Then you define a list below it. One space off in indentation, and the parser may treat subsequent lines of the multi-line block as children of the list. Result: the worldview is truncated, the list structure is broken, no error is reported, and the engine behaves unexpectedly.

Even more subtle: Chinese full-width spaces (　) and English half-width spaces () are visually indistinguishable. A creator accidentally types a full-width space instead of a half-width one — YAML parsers don't treat it as indentation. They either throw a syntax error or, worse, misidentify the entire block as a key. Without syntax highlighting, this is almost impossible to debug by eye.

The creator isn't reading content; they're constantly verifying "how many spaces are on this line." For a hundred-line contract, this cognitive burden never stops.

YAML's simplicity is a mirage. It's friendly to people, but to programs, its rules are more complex and unpredictable than JSON's.

V. Plain Text: Free but Ambiguous

Since structured formats have problems, why not skip structure entirely and just write plain text?

Like this:

角色名是贝利亚奥特曼。
世界观是光之国。
规则是如果用户提到攻击，就执行攻击。

For creators, this is the most natural way — zero learning curve.

But there's a problem: the program can't understand it. It doesn't know whether the "是" in "角色名是贝利亚奥特曼" is a declaration or a description. It doesn't know the relationship between "世界观是光之国" and the next sentence "规则是...". Natural language is clear to humans, but to programs, it's ambiguous, imprecise, and unparseable.

If I used plain text, I'd have to design an implicit convention — recognizing blocks by keyword matching, distinguishing entries by line breaks. That's harder to guarantee correctness than an explicit syntax.

Plain text is most friendly to creators, but almost unfriendly to programs.

VI. Three Options Compared

Format	Creator-Friendly	Program-Friendly	Core Problem
JSON	❌ No	✅ Yes	Escaping hell, unreadable error messages
YAML	⚠️ Partial	✅ Yes	Indentation sensitivity, multi-line vs. list confusion
Plain Text	✅ Yes	❌ No	Ambiguous structure, unparseable

I needed a format that: reads like a document, but has structure. It had to satisfy two conditions simultaneously:

Creators can write naturally, without learning JSON escaping or YAML indentation rules
Programs can parse precisely, and on error, tell the creator the exact location and reason

This meant I couldn't use any existing general-purpose format — I needed to design one specifically for the "narrative contract" scenario.

Even if only one out of ten users is a minimalist who craves a simpler config — that's still 10%, if you round it. So I decided to go all in on the custom format.

VII. .meph Design Principles

Back to that .meph contract from the beginning. Its design is based on three principles:

1. Use human language for boundaries, eliminate bracket-phobia

Creators see 【角色名】, not { and }. Chinese guillemets are more natural than curly braces for Chinese-speaking creators. 【角色名】 itself says what this section contains — no comments needed.

More importantly, block titles are restricted to a whitelist (角色名, 锚点, 规则, 状态, etc.). If a creator writes 【脚色名】 (a typo), the parser won't treat it as a block start — the creator will get an error pointing to that exact line.

(The specific message depends on whether the typo appears inside a block or outside one, but the line number is always precise.)

2. Distinguish "semantic blocks" rather than "data structures"

In JSON, the creator decides whether to use an object or an array — that's an implementation detail. In .meph, the creator only needs to know "this is a list" or "this is a paragraph." The parser identifies the structure based on the block title — the creator doesn't declare it.

3. Syntax mirrors natural logic

Rules use the intuitive [name] if condition -> action form. Condition logic uses readable expressions like 包含 "keyword" and 状态.key > value, not symbolic operators.

VIII. The Cost

This design doesn't come without cost:

The parser must be handwritten: I can't use json.Unmarshal or yaml.Unmarshal — I have to write my own lexer and parser
The whitelist must be maintained: adding a new block type means updating the knownBlocks list
Documentation is required: creators need to learn the format — though the learning curve is lower than JSON's, it's still a curve
Tooling is absent: no off-the-shelf syntax highlighting, formatting, or validation tools

But the deciding factor is simple: who writes this file?

If it's a programmer writing for a program, JSON is fine. If it's a creator writing for a program, you need a "human-centric" format. And the target users of a narrative engine are creators — people who write stories.

I believe this trade-off is worth it.

IX. Summary

This post answered the question "what format to use?" The answer is .meph — a custom text format designed specifically for narrative contracts, optimized for creator experience.

But "design" only solves half the problem. The next post puts theory aside and walks through writing a real contract from scratch — so you can see what it actually feels like to use this format.

GitHub: https://github.com/yuelinghuashu/mephisto

From Code to npm: Vue 3 Component Library Publishing Guide

yuelinghuashu — Wed, 24 Jun 2026 08:21:46 +0000

A complete record of publishing moongate-vue from build to npm, including 2FA, WebAuthn, registry switching, and automation scripts.

This article covers: nrm registry management, 2FA configuration, WebAuthn setup, local linking for testing, automated release scripts, and a pre-publish checklist.

I. Introduction

After the component library is developed, the final and most critical step is: publishing to npm. This process may seem simple, but it hides many practical challenges: package name conflicts, mandatory 2FA, security key (WebAuthn) issues, and frequent registry switching.

This article, as the final installment of the series, documents every obstacle I encountered while publishing moongate-vue and their solutions.

II. Pre-Publish Preparation

2.1 Check Build Outputs

Before publishing, ensure the outputs exactly match the build matrix we designed in the third article:

# Build the component library
pnpm run build

# Check the dist directory
ls dist/
# Should see:
# - index.mjs   (ES Module, for modern bundlers)
# - index.cjs   (CommonJS, for SSR / Node)
# - index.d.ts  (TypeScript declarations)
# - style.css   (Bundled styles)

2.2 Verify `package.json` Distribution Contract

These fields determine how the host project correctly resolves your components:

{
  "name": "moongate-vue",
  "version": "0.0.1",
  "type": "module",
  "main": "./dist/index.cjs",
  "module": "./dist/index.mjs",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "import": "./dist/index.mjs",
      "require": "./dist/index.cjs",
      "types": "./dist/index.d.ts"
    },
    "./style.css": "./dist/style.css"
  },
  "files": ["dist"],
  "sideEffects": ["*.css"],
  "peerDependencies": {
    "vue": "^3.0.0"
  }
}

💡 Bundle size tip: The files field is an allowlist. With ["dist"], npm will only upload the dist directory. package.json, README.md, and LICENSE are always included automatically.

2.3 Manage npm Registries with nrm

You must use the official registry to publish. If you previously switched to a mirror for faster downloads, use nrm for quick switching:

# Install nrm globally
npm install -g nrm

# List all available registries
nrm ls

# Add a mirror if missing
nrm add npmmirror https://registry.npmmirror.com

# Switch to the official registry (required for publishing)
nrm use npm

# Check the current registry
nrm current

2.4 Local Integration Testing

Before publishing to npm, test the library in a real project. My local testing workflow:

# 1. In the component library directory: build + link globally
pnpm build
pnpm link --global

# 2. In the test project directory: link the local library
pnpm link /absolute/path/to/moongate-vue  # Replace with your actual path

This approach doesn't require modifying the test project's package.json, and the link path is clear and controllable.

Testing checklist:

[ ] Components render correctly
[ ] Styles import correctly (import 'moongate-vue/style.css')
[ ] TypeScript type hints work
[ ] HMR works

Note: To completely remove the link after testing, manually delete the "moongate-vue": "link:../moongate-vue" entry from package.json, then run pnpm install to restore the normal version from npm. If you only need to temporarily break the link while keeping the configuration, remove node_modules and reinstall.

III. Tackling Two-Factor Authentication (2FA)

npm now requires 2FA for publishing to prevent supply chain attacks. npm has fully adopted the WebAuthn (Security Key) mode.

3.1 Browser Choice and Network Environment

⚠️ Important: npm's WebAuthn verification (e.g., Windows Hello or Touch ID) attempts to communicate with external verification services. In some network environments, the security key popup in Chrome/Edge may time out or fail to respond.

Make sure your network environment is stable and can reliably access external services before configuring or publishing.

Browser	Recommended Setup	Success Rate
Chrome	Stable internet connection	Very high
Edge	Works in most environments	High
Firefox	Not recommended	Low

3.2 Recommended: Configure Security Key via Web UI

Log in to npmjs.com.
Click avatar → Account → Two-Factor Authentication.
Choose Security Key (recommended, can use fingerprint or Face ID) or Authenticator App.
Follow the prompts to complete the setup.

3.3 CI/CD Automation Alternative: Granular Access Token

If you're publishing in a CI environment (e.g., GitHub Actions) or cannot pass 2FA locally (e.g., network restrictions), generate a Granular Access Token to bypass 2FA:

Log in to npm → click avatar → Access Tokens.
Select Generate New Token → Granular Access Token.
Grant Read and Write permissions.
Critical: check "Bypass two-factor authentication for automation".
Add the token to your local .npmrc:

//registry.npmjs.org/:_authToken=your_granular_token_value

IV. Standardized Publishing Workflow

Follow these atomic steps in order. Incorrect order may invalidate versions or cause publication failures.

4.1 Manual Publishing Steps

Lock the registry: Run nrm use npm to ensure the local registry points to the official source.
Login: Run npm login. Enter your username and password. The terminal will print an interactive URL for 2FA authorization.
Bump version: Run npm version patch|minor|major following semantic versioning.
- npm version patch (bug fix, 0.0.7 → 0.0.8)
- npm version minor (new feature, 0.0.7 → 0.1.0)
- npm version major (breaking change, 0.0.7 → 1.0.0)
Publish: Run npm publish --access public. If your package name is scoped (e.g., @moongate/vue), the --access public flag is required.

4.2 Automated Release Script

Manual registry switching, version bumping, tagging, publishing, and switching back is tedious and error-prone. Here's a step-by-step release script in package.json:

{
  "scripts": {
    "release:pre": "nrm use npm && npm run build",
    "release:version": "npm version patch --no-git-tag-version",
    "release:tag": "git add package.json && git commit -m \"chore: release v$(node -p 'require(\"./package.json\").version')\" && git tag v$(node -p 'require(\"./package.json\").version')",
    "release:publish": "npm publish --access public",
    "release:post": "echo '✅ Done! To switch back to mirror, run: nrm use npmmirror'",
    "release": "npm run release:pre && npm run release:version && npm run release:tag && npm run release:publish && npm run release:post"
  }
}

Run npm run release. If any step fails, the process stops immediately — no leftover tags or unintended registry switches.

V. Pre-Publish Final Checklist

Before running the publish command, verify these items:

[ ] Build succeeds: pnpm run build completes without errors.
[ ] Artifacts complete: dist/ contains .mjs, .cjs, .d.ts, and .css.
[ ] Types valid: dist/index.d.ts is non-empty and exports all component type contracts.
[ ] Clean version: npm version has been run; the version number has never existed on npm.
[ ] Local verification: Tested via pnpm link in a real project (see 2.4), confirming components render correctly and styles import properly.

VI. FAQ

Q1: 403 Forbidden or 404 Not Found on publish?

A: 403 usually means the package name is already taken, or you haven't run npm login (or your credentials expired). 404 means you forgot to run nrm use npm and are publishing to a read-only mirror.

Q2: Security key popup doesn't appear during 2FA?

A: This is usually a network issue. WebAuthn depends on external services. Confirm your network can reliably access these services. If still failing, use the Granular Access Token approach (section 3.3).

Q3: Styles don't load after installation (blank page)?

A: Two things to check:

Your package.json has "sideEffects": ["*.css"]. Without this, bundlers may tree-shake the CSS.
Users must explicitly import styles:

   import 'moongate-vue/style.css'

Q4: Local linked library updates don't take effect?

A: Rebuild with pnpm build, then re-link in the test project. If still not working, manually delete the link: entry from package.json, run pnpm install, then re-link.

VII. Conclusion

With the terminal output + moongate-vue@0.0.1, my Vue 3 component library is now available to developers worldwide.

From the design token specification in the first article, to the thin-wrapper philosophy, the type backtracking of complex components, and finally the industrial-grade npm distribution — five articles, one complete engineering cycle for a modern front-end component library.

Packaging and publishing is not the end, but the true beginning of a component library's lifecycle.

This article is part of the **Vue 3 Component Library Development Guide* series.*

The original Chinese version is available on my blog: moongate.top.

Try the component library on npm: moongate-vue

Vue 3 Complex Component Development: API Design for Select and Pagination

yuelinghuashu — Fri, 19 Jun 2026 11:58:12 +0000

From data format adaptation to route synchronization, diving into the design principles and logic reuse of complex components

This article covers: flexible data format support (object arrays, string arrays, number arrays), custom field mapping (labelKey/valueKey), route state synchronization (pagination + filters bound to URL), keyboard navigation (without interfering with input fields), SSR adaptation (the "last mile" for component libraries), logic extraction and reuse (composables), and industrial-grade details: type backtracking, defensive programming, and extreme edge case handling.

I. Introduction

If writing the Button component is about enjoying the "paint-like beauty" of CSS variables, then writing Select and Pagination is about wrestling in the "quagmire" of native HTML legacy baggage. Simple components are one-way data consumers, while complex components are data adapters (supporting multiple formats) and state synchronizers (coordinating with routing and keyboard events).

This article uses Select and Pagination as examples to demonstrate the development approach for complex components, covering:

Flexible data format support (object arrays, string arrays, number arrays)
Custom field mapping (labelKey / valueKey)
Route state synchronization (page numbers and filters bound to URL)
Accessibility features (keyboard navigation, mobile gestures)
SSR adaptation (the "last mile" for component libraries)
Logic extraction and reuse (composables)
Industrial-grade details: type backtracking, defensive programming, event pollution prevention, extreme edge case handling

II. Select Dropdown: The Data Adapter

The Select component needs to receive a list of options and allow the user to select one. Real-world APIs may return object arrays, string arrays, or even number arrays, so the component must have robust data adaptation capabilities.

2.1 Requirements Analysis

Support object arrays { label, value } (default)
Support custom field names (labelKey / valueKey)
Support string arrays ['Option A', 'Option B']
Support number arrays [1, 2, 3]
Provide a placeholder (non-selectable default option)
Support disabled options (disabled: true)
Support error state, sizing, disabled, and other common attributes
Must solve the native <select> type trap (always returns strings)
Support native <form> submission (via name attribute)

2.2 API Design and Type Preservation

To avoid type pollution from any, use union types to narrow the scope.

type SelectOption = string | number | Record<string, any>

interface Props {
  modelValue?: string | number
  options?: SelectOption[]      // Union type, rejects bare any
  labelKey?: string             // Default 'label'
  valueKey?: string             // Default 'value'
  placeholder?: string
  name?: string                 // Supports native form submission
  size?: 'sm' | 'md' | 'lg'
  disabled?: boolean
  error?: boolean
}

2.3 Internal Implementation: Defensive Programming + Type Backtracking

<template>
  <select
    class="mg-select"
    :class="[`mg-select-${size}`, { 'mg-select-error': error }]"
    :value="modelValue"
    :disabled="disabled"
    :name="name"
    v-bind="$attrs"
    @change="handleChange"
  >
    <option v-if="placeholder" value="" disabled hidden>
      {{ placeholder }}
    </option>
    <option
      v-for="item in options || []"
      :key="getValue(item)"
      :value="getValue(item)"
      :disabled="item.disabled"
    >
      {{ getLabel(item) }}
    </option>
  </select>
</template>

<script setup lang="ts">
// ... type definitions

const getLabel = (item: any): string => {
  if (item === null || item === undefined) return ''
  if (typeof item !== 'object') return String(item)
  const label = item[props.labelKey]
  return label !== undefined ? String(label) : String(item)
}

const getValue = (item: any): any => {
  if (item === null || item === undefined) return undefined
  if (typeof item !== 'object') return item
  const val = item[props.valueKey]
  return val !== undefined ? val : item
}

// 🔥 Core: Solving the fatal issue where native select always returns strings
const handleChange = (event: Event) => {
  const target = event.target as HTMLSelectElement
  const rawValue = target.value

  // Attempt to find the original type (number or object value) from the original options
  const originalItem = (props.options || []).find(item => String(getValue(item)) === rawValue)
  const finalValue = originalItem !== undefined ? getValue(originalItem) : rawValue

  emit('update:modelValue', finalValue)
  emit('change', finalValue)
}
</script>

Defensive Programming Note: options || [] ensures that even if undefined is passed in externally or loading is delayed, the component won't break. The type backtracking logic ensures that number values bound via v-model won't accidentally become strings. Explicit support for the name attribute allows <select> to participate in native form submission.

2.4 Usage Examples

<!-- Object array (default fields) -->
<Select v-model="category" :options="categories" name="category" />

<!-- Custom field names -->
<Select v-model="category" :options="cats" label-key="name" value-key="id" />

<!-- String array (type preserved automatically) -->
<Select v-model="color" :options="['Red', 'Green', 'Blue']" />

<!-- Number array -->
<Select v-model="num" :options="[10, 20, 30]" />

<!-- Disabled options -->
<Select v-model="status" :options="statusOptions" />

III. Pagination Component: The State Synchronizer

The Pagination component needs to work with the current page number and items per page, providing previous/next buttons and supporting direct input for page jumps. In Nuxt projects, the page number often needs to be synchronized with the URL, and keyboard left/right arrow navigation must be supported without interfering with input fields.

3.1 Requirements Analysis

Display current page / total pages
Previous/next buttons (disabled at boundaries)
Clicking the current page number turns it into an input field for direct page jumps
Synchronize with route query (update URL when page changes)
Support keyboard left/right arrow navigation (must not interfere with input fields)
Extreme edge case defense (empty input, out-of-range values, etc.)
Size adaptation

3.2 API Design

interface Props {
  currentPage: number       // v-model:current-page
  totalPages: number
  size?: 'sm' | 'md' | 'lg'
}

3.3 Core Implementation (with Extreme Edge Case Defense)

<template>
  <nav class="mg-pagination" :class="`mg-pagination-${size}`">
    <button class="mg-pagination-btn" :disabled="currentPage === 1" @click="goPrev">
      Previous
    </button>

    <span v-if="!editing" class="mg-pagination-current" @click="startEdit">
      {{ currentPage }}
    </span>
    <input
      v-else
      ref="inputRef"
      v-model="inputPage"
      type="number"
      class="mg-pagination-input"
      :min="1"
      :max="totalPages"
      @blur="commit"
      @keyup.enter="commit"
    />

    <span class="mg-pagination-sep">/</span>
    <span class="mg-pagination-total">{{ totalPages }}</span>

    <button class="mg-pagination-btn" :disabled="currentPage === totalPages" @click="goNext">
      Next
    </button>
  </nav>
</template>

<script setup lang="ts">
import { ref, nextTick } from 'vue'

const props = defineProps<{ currentPage: number; totalPages: number; size?: string }>()
const emit = defineEmits<{ 'update:currentPage': [page: number] }>()

const editing = ref(false)
const inputPage = ref(props.currentPage)
const inputRef = ref<HTMLInputElement>()

const goPrev = () => { if (props.currentPage > 1) emit('update:currentPage', props.currentPage - 1) }
const goNext = () => { if (props.currentPage < props.totalPages) emit('update:currentPage', props.currentPage + 1) }

const startEdit = () => {
  editing.value = true
  inputPage.value = props.currentPage
  nextTick(() => inputRef.value?.focus())
}

const commit = () => {
  editing.value = false
  const raw = inputPage.value
  const pageNum = parseInt(String(raw), 10)

  // Invalid input: abandon without updating the page
  if (isNaN(pageNum)) return

  let page = Math.min(Math.max(pageNum, 1), props.totalPages)
  if (page !== props.currentPage) {
    emit('update:currentPage', page)
  }
}
</script>

3.4 Keyboard Navigation Logic (Composable)

To keep the component clean, extract keyboard events into useKeyboardPagination, ensuring they don't interfere with input fields.

// composables/useKeyboardPagination.ts
import { onMounted, onUnmounted } from 'vue'

export function useKeyboardPagination(onPrev: () => void, onNext: () => void) {
  const handleKeyDown = (e: KeyboardEvent) => {
    // 🔥 Critical: Don't trigger pagination if focus is in an input or textarea
    const target = e.target as HTMLElement
    if (target.tagName === 'INPUT' || target.tagName === 'TEXTAREA') return

    if (e.key === 'ArrowLeft') onPrev()
    if (e.key === 'ArrowRight') onNext()
  }

  onMounted(() => window.addEventListener('keydown', handleKeyDown))
  onUnmounted(() => window.removeEventListener('keydown', handleKeyDown))
}

3.5 Route Synchronization and All-in-One Composable

To demonstrate the elegance of "one-click assembly", combine page route synchronization, keyboard events, and navigation methods into a single all-in-one composable.

// composables/useMoongatePagination.ts
import { ref, type Ref } from 'vue'
import { useRouteQueryNumber } from './useRouteQuery'
import { useKeyboardPagination } from './useKeyboardPagination'

export function useMoongatePagination(totalPages: Ref<number>) {
  const page = useRouteQueryNumber('page', { defaultValue: 1 })

  const goPrev = () => { if (page.value > 1) page.value-- }
  const goNext = () => { if (page.value < totalPages.value) page.value++ }

  // Keyboard events are assembled internally
  useKeyboardPagination(goPrev, goNext)

  return { page, goPrev, goNext }
}

Usage in a business page:

<script setup>
const totalPages = ref(10)
const { page, goPrev, goNext } = useMoongatePagination(totalPages)
// No need to handle keyboard events separately — everything is automatic
</script>

<template>
  <Pagination v-model:current-page="page" :total-pages="totalPages" />
  <!-- You can also use custom buttons linked to the pagination state -->
  <button @click="goPrev">Previous</button>
  <button @click="goNext">Next</button>
</template>

IV. Data and State Flow in Complex Components

┌─────────────────────────────────────────────────────────────┐
│                    Complex Component Data Flow               │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐     │
│  │ External    │ -> │ Data        │ -> │ Internal    │     │
│  │ Data        │    │ Adapter     │    │ State       │     │
│  │ (options)   │    │ (getLabel/  │    │ (selected)  │     │
│  └─────────────┘    │  getValue)  │    └──────┬──────┘     │
│                     └─────────────┘           │            │
│                                              ↓            │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐     │
│  │ Global      │ <- │ State       │ <- │ User        │     │
│  │ Environment │    │ Synchronizer│    │ Interaction │     │
│  │ (route/key) │    │ (watch/     │    │ (click/     │     │
│  └─────────────┘    │  event)     │    │  keyboard)  │     │
│                     └─────────────┘    └─────────────┘     │
└─────────────────────────────────────────────────────────────┘

V. Testing Strategies for Complex Components

Concern	Simple Components (Button)	Complex Components (Select / Pagination)
Testing Strategy	Snapshot testing, simple click event triggering	State snapshot combinations, edge case testing (page 0 / exceeding total pages), DOM focus and keyboard simulation testing, type backtracking robustness testing

VI. SSR Adaptation: The "Last Mile" of Component Libraries

Complex components often rely on browser APIs (document, window). In SSR environments, they directly throw document is not defined errors. This section uses Popover, Tooltip, and Drawer as examples to demonstrate how to systematically adapt to SSR.

6.1 Root Cause

During server-side rendering, onMounted does not execute, but watch with immediate: true and top-level code in <script setup> do execute. The following code crashes in SSR:

// ❌ SSR error: document is not defined
watch(() => modelValue.value, (val) => {
  if (val) {
    document.body.style.overflow = 'hidden'  // ← document does not exist on server
  }
}, { immediate: true })

6.2 Unified Solution

Step 1: Define the isBrowser guard

const isBrowser = typeof window !== 'undefined' && typeof document !== 'undefined'

Step 2: Add guards to all document/window access points

// ✅ Correct approach
watch(() => modelValue.value, (val) => {
  if (!isBrowser) return  // SSR safe
  if (val) {
    document.body.style.overflow = 'hidden'
    window.addEventListener('keydown', handleKeydown)
  }
}, { immediate: true })

onMounted(() => {
  if (!isBrowser) return
  // Only execute DOM operations in browser environment
})

onBeforeUnmount(() => {
  if (!isBrowser) return
  document.body.style.overflow = ''
  window.removeEventListener('keydown', handleKeydown)
})

6.3 Components Requiring SSR Adaptation

Component	Browser APIs Involved	Handling Approach
Drawer / Modal	`document.body.style.overflow`, `addEventListener`	Add guards in watch + onBeforeUnmount
Popover / Tooltip	`window.innerWidth/Height`, `getBoundingClientRect`, `MutationObserver`	Place all inside onMounted
useToast / useMessage	`document.createElement`, `appendChild`	Add `if (!isBrowser) return` to imperative calls

6.4 Verification

After adaptation, the component library can run seamlessly in SSR frameworks like Nuxt 4 and VitePress, without requiring additional configuration from users.

VII. Summary

Concern	Simple Components (Button)	Complex Components (Select / Pagination)
Number of Props	Few (5-8)	Many (10+)
Data Format	Fixed (string)	Flexible (supports multiple arrays, configurable fields, type preservation)
State Management	No internal state	May have internal edit state, input visibility toggling, extreme edge case defense
External Dependencies	None	Routing, keyboard events, gestures
Logic Reuse	Not needed	Strongly recommended to extract composables, can integrate into all-in-one functions
Defensive Programming	Low	High (needs to handle undefined data, type backtracking, empty input recovery)
Native Form Integration	Auto-transparent `name`	Explicit `name` attribute support, can participate in `<form>` submission
Testing Strategy	Snapshot, event triggering	State combinations, edge cases, keyboard simulation, type backtracking

An excellent complex component acts like a vacuum cleaner internally, accommodating all kinds of quirky backend data formats (via key mapping and type backtracking), while externally interacting with the global environment (routes, window keyboard events) with gentlemanly restraint. High cohesion, low coupling — this principle is fully embodied in both types of components.

Vue 3 Simple Component Development: API Design from the Button Component

yuelinghuashu — Fri, 12 Jun 2026 06:00:22 +0000

Minimalism is not crudeness, restraint is not deficiency — drawing inspiration from Nuxt UI v4, how to design a well-crafted component API

This article covers: Props definition, variant system (variant + color), size trade-offs (why remove xs/xl), slot design (label prop vs default slot), loading state handling (including CLS prevention), accessibility attributes, and a comparison table with mainstream UI libraries.

I. Background and Reference

In previous articles, we discussed the concept of design tokens over atomic CSS, and the architecture of CSS-first + thin component wrappers. But one question remains unanswered: How should a single component's API be designed?

Early in the design process, I deeply referenced Nuxt UI v4's approach. Nuxt UI v4 consolidates complex styles and interactions into a few core dimensions — variant/color/size. This is exactly what I wanted: encapsulate complexity inside the component, exposing only the most streamlined API to the outside.

This article uses the Button component as an example to walk through my design trade-offs and thought process step by step.

II. Starting from Requirements: What Does a Button Need?

A button component's most basic functionality:

Display text
Trigger events on click
Disabled state
Different styles (primary, secondary, danger, etc.)

But is that enough? Let's look at real usage scenarios:

<!-- Button with icon -->
<Button>
  <template #icon>🔍</template>
  Search
</Button>

<!-- Loading state -->
<Button loading>Submitting</Button>

<!-- Block button (full width) -->
<Button block>Full Width Button</Button>

<!-- Different sizes -->
<Button size="sm">Small</Button>

After analysis, the Button component needs to support:

Requirement	Implementation
Text content	Default slot or `label` prop
Click event	`click` event
Disabled state	`disabled` prop
Loading state	`loading` prop
Different styles	`variant` + `color`
Different sizes	`size` prop
Block width	`block` prop
Icon	`#icon` slot

III. Props Design: Types, Defaults, Priority

3.1 Base Props

interface Props {
  label?: string;      // Button text
  disabled?: boolean;  // Disabled state
  loading?: boolean;   // Loading state
  block?: boolean;     // Block level
}

Default value design:

const props = withDefaults(defineProps<Props>(), {
  label: "",
  disabled: false,
  loading: false,
  block: false,
});

3.2 Variant System: variant + color

Common button types include: primary, secondary, outline, ghost. Inspired by Nuxt UI v4's variant + color design, I chose to completely decouple "visual mode" from "semantic color".

type Variant = "filled" | "outline";
type Color = "primary" | "success" | "warning" | "error";

Why keep only filled and outline, removing ghost?

Variant	Usage Frequency	Keep?
`filled`	🔥🔥🔥🔥🔥 Extremely high	✅ Keep
`outline`	🔥🔥🔥🔥 High	✅ Keep
`ghost`	🔥 Low	❌ Removed (can be replaced by `outline`)

Similarly, keep only 4 colors:

Color	Usage Frequency	Keep?
`primary`	🔥🔥🔥🔥🔥 Extremely high	✅ Keep
`success`	🔥🔥🔥 Medium	✅ Keep
`warning`	🔥 Low	✅ Keep
`error`	🔥🔥 Medium	✅ Keep
`neutral`	🔥 Low	❌ Removed (can be replaced by `outline`)

3.3 Size Design

type Size = "sm" | "md" | "lg";

Compared with Nuxt UI v4's five sizes (xs, sm, md, lg, xl), I made a simplification. I removed xs and xl because the smallest use cases can be covered by Badge or other non-button components, and I rarely encounter extra-large buttons in a personal blog context.

Default size selection: Mainstream UI libraries (Naive UI, PrimeVue, etc.) have default button heights around 32-34px, which corresponds to our sm, so the default size is sm.

const props = withDefaults(defineProps<Props>(), {
  size: "sm", // default small
});

3.4 Icon Design: Only Use Slots

To keep things minimalist, the Button component does not provide an icon prop, only the #icon slot. When users need an icon, they simply put content in the slot:

<Button>
  <template #icon>🔍</template>
  Search
</Button>

Although this requires a few more characters, it avoids confusion between prop and slot priority, and better follows the single responsibility principle. Also, the slot can accept any content (strings, emojis, icon components), with complete flexibility.

Design consideration: Nuxt UI v4 provides an icon prop and multiple icon-related attributes (leading-icon/trailing-icon). But in a personal blog context, the vast majority of icon buttons are simply "icon + text", and using a slot is sufficient for all use cases, reducing learning and maintenance costs.

IV. Slot Design: Default Slot vs label Prop

To support both quick writing and custom content, provide both label prop and default slot:

<span class="mg-button-label">
  <slot>{{ label }}</slot>
</span>

If default slot content is provided, display it
Otherwise, display the label prop

Both usage styles are supported:

<!-- Using label prop -->
<Button label="Submit" />

<!-- Using default slot -->
<Button>Submit</Button>

V. State Handling

5.1 Disabled State

Both disabled and loading disable the button:

const isDisabled = computed(() => props.disabled || props.loading);

<button :disabled="isDisabled">

5.2 Loading State

Show a spinning animation when loading, hide icon and text:

<template v-if="loading">
  <span class="mg-button-loading-icon" />
</template>
<template v-else>
  <span v-if="hasIconSlot" class="mg-button-icon">
    <slot name="icon" />
  </span>
  <span v-if="hasLabel" class="mg-button-label">
    <slot>{{ label }}</slot>
  </span>
</template>

Pure CSS loading animation:

.mg-button-loading-icon {
  width: 1rem;
  height: 1rem;
  border: 2px solid currentColor;
  border-top-color: transparent;
  border-radius: 50%;
  animation: mg-button-spin 0.6s linear infinite;
}
@keyframes mg-button-spin {
  to {
    transform: rotate(360deg);
  }
}

VI. CSS Styling

6.1 Base Styles

Buttons use inline-flex layout, content centered both horizontally and vertically, with straight corners (--ui-radius-none), padding and font size using design tokens.

.mg-button {
  display: inline-flex;
  align-items: center;
  justify-content: center;
  gap: var(--ui-spacing-sm);
  font-weight: 500;
  transition: all var(--ui-motion-duration-neural) ease;
  cursor: pointer;
  border-radius: var(--ui-radius-none);
  border: none;
  background: transparent;
  white-space: nowrap;
  padding: var(--ui-spacing-sm) var(--ui-spacing-md);
  font-size: var(--ui-typography-size-body);
}

6.2 Size Variants

Size	Padding	Font Size
`sm`	`sm` / `md`	`--ui-typography-size-code` (13px)
`md`	`md` / `lg`	`--ui-typography-size-body` (15px)
`lg`	`lg` / `xl`	`1.125rem` (18px)

.mg-button-sm {
  padding: var(--ui-spacing-sm) var(--ui-spacing-md);
  font-size: var(--ui-typography-size-code);
}
.mg-button-md {
  padding: var(--ui-spacing-md) var(--ui-spacing-lg);
  font-size: var(--ui-typography-size-body);
}
.mg-button-lg {
  padding: var(--ui-spacing-lg) var(--ui-spacing-xl);
  font-size: 1.125rem;
}

6.3 Block Button

.mg-button-block {
  width: 100%;
}

6.4 Icon and Label Containers

The icon container uses inline-flex with line-height: 0 to eliminate line-height influence. SVG or iconify icons inside are forced to block display with width/height set to 1em.

.mg-button-icon {
  display: inline-flex;
  align-items: center;
  justify-content: center;
  flex-shrink: 0;
  line-height: 0;
}
.mg-button-icon svg,
.mg-button-icon .iconify {
  display: block;
  width: 1em;
  height: 1em;
}
.mg-button-label {
  display: inline-flex;
  align-items: center;
}

6.5 Solving Icon-Only Button Centering

When a button has only an icon and no text, the empty .mg-button-label occupies space and breaks centering. Hide empty labels with the :empty pseudo-class:

.mg-button-label:empty {
  display: none;
}

Also check for real content before rendering the label:

const hasLabel = computed(() => !!props.label || !!slots.default);

<span v-if="hasLabel" class="mg-button-label">
  <slot>{{ label }}</slot>
</span>

6.6 Variant Styles

filled and outline variants correspond to filled background and transparent background with border, respectively. Colors are dynamically combined via the color prop. For example, .mg-button-filled-primary uses --ui-primary as background color.

VII. Accessibility

Add ARIA attributes to improve accessibility:

<button
  :aria-busy="loading"
  :aria-disabled="disabled || loading"
>

Screen readers can correctly read the button's loading and disabled states.

VIII. Attribute Inheritance

Use v-bind="$attrs" to pass through native attributes:

<button v-bind="$attrs">

Users can directly pass attributes like id, name, data-*, aria-*:

<Button id="submit-btn" name="submit" data-testid="submit">
  Submit
</Button>

IX. Final Code

<template>
  <button
    v-bind="$attrs"
    class="mg-button"
    :class="[
      `mg-button-${variant}-${color}`,
      `mg-button-${size}`,
      { 'mg-button-block': block, 'mg-button-loading': loading },
    ]"
    :disabled="disabled || loading"
    :aria-busy="loading"
    :aria-disabled="disabled || loading"
    @click="handleClick"
  >
    <template v-if="loading">
      <span class="mg-button-loading-icon" />
    </template>

    <template v-else>
      <span v-if="hasIconSlot" class="mg-button-icon">
        <slot name="icon" />
      </span>
      <span v-if="hasLabel" class="mg-button-label">
        <slot>{{ label }}</slot>
      </span>
    </template>
  </button>
</template>

<script setup lang="ts">
import { useSlots, computed } from "vue";

const slots = useSlots();
const hasIconSlot = computed(() => !!slots.icon);
const hasLabel = computed(() => !!props.label || !!slots.default);

type Variant = "filled" | "outline";
type Color = "primary" | "success" | "warning" | "error";
type Size = "sm" | "md" | "lg";

interface Props {
  label?: string;
  variant?: Variant;
  color?: Color;
  size?: Size;
  disabled?: boolean;
  loading?: boolean;
  block?: boolean;
}

const props = withDefaults(defineProps<Props>(), {
  label: "",
  variant: "filled",
  color: "primary",
  size: "sm",
  disabled: false,
  loading: false,
  block: false,
});

const emit = defineEmits<{ click: [event: MouseEvent] }>();

const handleClick = (event: MouseEvent) => {
  if (props.disabled || props.loading) return;
  emit("click", event);
};
</script>

X. Comparison with Mainstream UI Libraries

API Feature	Moongate UI	Nuxt UI v4	Naive UI (NButton)	PrimeVue (Button)
Core style	`variant` (filled/outline)	`variant` + `color`	`type`	`severity` + `variant`
Size	`size` (sm/md/lg)	`size` (xs/sm/md/lg/xl)	`size` (small/medium/large)	`size` (small/medium/large)
Disabled	`disabled`	`disabled`	`disabled`	`disabled`
Loading	`loading`	`loading` / `loadingAuto`	`loading`	`loading`
Block	`block`	`block`	`block`	`fluid`
Icon	`#icon` slot	`icon` / `leading-icon` / `trailing-icon` + slot	None	`icon` + `iconPos`
Extra styles	None	`square`	`dashed`, `circle`, `round`	`rounded`, `raised`, `outlined`

The comparison clearly shows:

Decoupling variant and color: variant focuses on "visual mode", color focuses on "semantic meaning"
Streamlined sizing: 3 sizes are sufficient for personal blog scenarios
Icon flexibility: The #icon slot achieves the same effect as props, with more flexibility
Semantic naming: Using filled and outline more accurately describes the visual style

XI. Additional Detail: The Width Change Trap in Loading State

There's a common but easily overlooked issue when using the loading attribute — "button width changes when loading". When the loading animation (e.g., a spinner) appears, it changes the button's internal children, usually causing the container to widen and layout shifts. This is essentially Cumulative Layout Shift (CLS).

An elegant solution: reserve space with min-width, and absolutely position the loading icon so it doesn't affect layout.

.mg-button {
  /* 1. Reserve enough space to ensure consistent width in loading and normal states */
  min-width: 88px;
}

.mg-button-loading .mg-button-label {
  opacity: 0;
}

.mg-button-loading-icon {
  /* 2. Absolutely position the loading icon centered, without affecting layout */
  position: absolute;
  top: 50%;
  left: 50%;
  transform: translate(-50%, -50%);
}

XII. Design Decision Summary

Decision	Reason
Remove `xs` size	Low usage frequency, simplify API
Remove `ghost` variant	Can be replaced by `outline`
Remove `neutral` color	Can be replaced by `outline` + default color
Default size `sm`	Mainstream UI libraries default to ~32px
Only use `#icon` slot	Avoid prop/slot confusion, keep it simple
`label` prop + default slot	Support both writing styles
Hide empty label	Solve icon-only button centering
`v-bind="$attrs"`	Pass through native attributes, maintain flexibility
`min-width` + absolute positioned loading icon	Prevent layout shift during loading

The original Chinese version is available on my blog: moongate.top.

Try the component library on npm: moongate-vue

Explore the component documentation: vue.moongate.top

CSS First + Thin Component Wrapper: A 10KB Component Library Practice

yuelinghuashu — Sat, 06 Jun 2026 01:30:10 +0000

From UnoCSS back to native CSS, a design token-driven component library solution.

This article covers: four-layer CSS architecture (colors, layout, components, main), the Button.vue implementation (no <style> block, ~50 lines), bundle size and maintainability comparison, and a minimal set of utility classes (only ~30 classes).

I. Recap: Conclusion from the First Article

In the previous article, I shared my failed attempt to map existing design tokens to UnoCSS. The core conclusions were:

Design tokens are the foundation; atomic CSS is just a layer of paint
Forcibly mapping only increases maintenance cost without real benefit
For projects with mature design tokens, atomic CSS is not a necessity

So, if not atomic CSS, how should a component library be written?

This article provides the answer.

II. The Final Architecture: Four-Layer CSS Files

The entire styling system is divided into four layers, with clear responsibilities and layered dependencies:

┌─────────────────────────────────────────────────────────────┐
│                   Design Token Layer (auto-generated)       │
│  ┌─────────────────────┐    ┌─────────────────────────────┐ │
│  │    colors.css       │    │       layout.css            │ │
│  │  Color tokens       │    │  Layout tokens              │ │
│  │  (40+ variables)    │    │  (spacing/font/animation)   │ │
│  │  【API layer】       │    │                             │ │
│  └──────────┬──────────┘    └─────────────┬───────────────┘ │
│             └──────────────┬──────────────┘                 │
│                            ↓                                │
│                   Component Style Layer (handwritten)       │
│  ┌─────────────────────────────────────────────────────┐   │
│  │                 components/                          │   │
│  │    Individual CSS files per component                │   │
│  │    (.mg-button, .mg-card, .mg-input...)              │   │
│  │            Reference var(--ui-*) tokens              │   │
│  └──────────────────────────┬──────────────────────────┘   │
│                             ↓                               │
│                       Entry Layer (handwritten)             │
│  ┌─────────────────────────────────────────────────────┐   │
│  │                    main.css                          │   │
│  │  Import token files + component files + global reset │   │
│  └─────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘

File Responsibilities

File/Directory	Responsibility	Generation
`colors.css`	Light/dark mode color tokens	Auto-generated by theme plugin
`layout.css`	Spacing, typography, animation, etc.	Auto-generated by theme plugin
`components/`	Individual CSS files per component (Button, Card, Input...)	Handwritten
`main.css`	Entry file + global reset + utilities	Handwritten

Design Tokens as API

In this architecture, colors.css is not just styling — it is the Configuration API of the component library. Users can customize the entire UI by modifying these CSS variables (e.g., --ui-primary, --ui-spacing-md) without touching any JavaScript logic. This is the core value of design tokens: complete separation of style configuration from code logic.

Engineering Benefit: Cross-Framework Reusability

This decoupling means that if I wanted to migrate from Vue to React or Svelte tomorrow, I would only need to rewrite ~50 lines of logic components. The core styling system (~500 lines of CSS) can be reused as-is, without any changes. This is something atomic CSS solutions that "bind styles to logic" can never achieve.

III. Minimal Component: Button.vue as an Example

With global CSS classes in place, a Vue component only needs to do three things:

Combine the correct class names
Handle interaction logic (click, disabled, loading)
Transparently pass slots

<script setup lang="ts">
import { useSlots, computed } from "vue";

const slots = useSlots();
const hasIconSlot = computed(() => !!slots.icon);

type Variant = "filled" | "outline";
type Color = "primary" | "success" | "warning" | "error";
type Size = "sm" | "md" | "lg";

interface Props {
  label?: string;
  variant?: Variant;
  color?: Color;
  size?: Size;
  disabled?: boolean;
  loading?: boolean;
  block?: boolean;
}

const props = withDefaults(defineProps<Props>(), {
  label: "",
  variant: "filled",
  color: "primary",
  size: "sm",
  disabled: false,
  loading: false,
  block: false,
});

const emit = defineEmits<{ click: [event: MouseEvent] }>();

const handleClick = (event: MouseEvent) => {
  if (props.disabled || props.loading) return;
  emit("click", event);
};
</script>

<template>
  <button
    class="mg-button"
    :class="[
      `mg-button-${variant}-${color}`,
      `mg-button-${size}`,
      { 'mg-button-block': block, 'mg-button-loading': loading },
    ]"
    :disabled="disabled || loading"
    :aria-busy="loading"
    :aria-disabled="disabled || loading"
    @click="handleClick"
  >
    <span v-if="loading" class="mg-button-loading-icon" />
    <span v-if="!loading && hasIconSlot" class="mg-button-icon">
      <slot name="icon" />
    </span>
    <span class="mg-button-label">
      <slot>{{ label }}</slot>
    </span>
  </button>
</template>

Component Features:

No <style> block — styles come entirely from global CSS
~50 lines of code, minimal and clear
Type-safe (TypeScript)
Supports accessibility attributes (aria-busy, aria-disabled) — minimal does not mean crude
Supports 8 props + 2 slots, covering daily use cases

IV. Dynamic Styles: Local CSS Variable Override

For stateful components like Button, in addition to preset combinations like filled-primary, you can also use local CSS variable overrides:

<!-- Custom color without modifying component source -->
<Button :style="{ '--btn-bg': '#ff6b6b' }" class="custom-button">
  Custom Color
</Button>

/* Add one line in components/Button.css */
.mg-button {
  background-color: var(--btn-bg, var(--ui-primary));
}

This makes components more flexible, even handling arbitrary user colors beyond the 4 preset options.

V. Usage Example

<template>
  <!-- Basic usage -->
  <Button label="Default Button" />

  <!-- With icon -->
  <Button icon="🔍" label="Search" />

  <!-- Loading state (auto-disables click) -->
  <Button loading label="Submitting" />

  <!-- Block button -->
  <Button block label="Full Width Button" />

  <!-- Complete combination -->
  <Button variant="outline" color="error" size="lg" block :loading="isDeleting">
    Delete Project
  </Button>
</template>

VI. Bundle Size and Maintainability Analysis

Bundle Size Data

Type	Raw Size	Gzipped
CSS (tokens + components)	~15 KB	~4 KB
JS (Button component)	~2 KB	~0.8 KB
Other components (on-demand)	~10 KB	~3 KB
Total	~27 KB	~8 KB

Maintainability Comparison

Dimension	Atomic Solution (UnoCSS Mapping)	This Solution
CSS size	On-demand, very small	~4 KB (gzipped)
Maintenance cost	Need to sync mapping config	Modify CSS directly
Cognitive load	Remember hundreds of class names and mapping logic	Only ~20 component class names
Readability	Template bloat, hard to see component hierarchy	Minimal template, semantic class names
Initial render	Requires JS to inject styles	Pure CSS, native browser rendering
Runtime environment	Requires Node + PostCSS/Vite plugin + config	Only needs browser with CSS Variables (98%+ global support)
Cross-framework reuse	Impossible	Styles can be reused across frameworks

VII. Minimal Utilities: A Tiny Set of Atomic Classes

Although I abandoned full atomic frameworks, commonly used layout utilities are still valuable. I wrote a minimal set of utility classes in main.css:

/* Layout */
.flex { display: flex; }
.inline-flex { display: inline-flex; }
.items-center { align-items: center; }
.justify-between { justify-content: space-between; }

/* Spacing (based on design tokens) */
.gap-2 { gap: var(--ui-spacing-sm); }
.p-4 { padding: var(--ui-spacing-lg); }
.mx-auto { width: fit-content; margin-left: auto; margin-right: auto; }

/* Size */
.w-full { width: 100%; }

/* Responsive patch (5 lines solving 80% of mobile issues) */
@media (max-width: 768px) {
  .sm-hidden { display: none !important; }
  .sm-flex-col { flex-direction: column !important; }
}

Features:

Only ~30 of the most commonly used classes, added as needed
Values bind to design tokens (var(--ui-spacing-*)), maintaining theme consistency
Responsive patch is only 5 lines, zero dependencies

Naming Freedom

Since these utilities are handwritten, you can name them according to your project preferences. If you dislike the Tailwind style, you can even call it .mobile-stack instead of .sm-flex-col. This naming freedom is one of the charms of native CSS over atomic frameworks.

VIII. Summary

Suitable Scenarios

✅ Projects with existing mature design tokens
✅ Personal blogs, small websites
✅ Component libraries that prioritize long-term maintainability
✅ Scenarios where complex toolchains are undesirable

Unsuitable Scenarios

❌ Projects starting from zero without design tokens
❌ Large design systems requiring dynamic theme switching
❌ Scenarios requiring extreme customization (different styles per component)

Key Takeaway

Often, we introduce complex toolchains to alleviate the anxiety of "writing CSS." But when you truly have a design token-driven underlying system, you realize CSS is no longer a pile of messy patches — it becomes a precise, elegant logical decomposition.

This solution totals less than 500 lines of code (CSS + components) and ~10KB after bundling, yet it fully supports the core functionality of a component library.

These 10KB represent not just a reduction in size, but a reduction in mental burden.

The original Chinese version is available on my blog: moongate.top.

Try the component library on npm: moongate-vue

Explore the component documentation: vue.moongate.top

Design Tokens vs Atomic CSS: A Failed Integration and the Path to Harmony

yuelinghuashu — Sun, 31 May 2026 02:10:45 +0000

A personal developer's attempt to map design tokens to UnoCSS failed the same day. But it resulted in a set of pragmatic boundaries.

This article covers: quantified comparison between design tokens and atomic CSS, the real configuration of the failed UnoCSS mapping, pragmatic boundaries between CSS variables and atomic tools, and when to abandon atomic CSS.

I. Starting Point: I Have a Complete Design Token System

My personal project moongate-vue started with just three CSS files:

colors.css : Light/dark dual theme, 40+ semantic color variables (--ui-primary, --ui-bg-muted...)
layout.css : Layout tokens for spacing, radius, shadow, animation, typography, breakpoints
main.css : Global component styles

This token system doesn't depend on any framework. Any component can access design constraints through var(--ui-spacing-md), var(--ui-primary). It's stable, intuitive, and maintainable — the foundation of my entire component library.

II. The Temptation: UnoCSS Lightweight and Atomic

I had heard about Tailwind's "heaviness", but UnoCSS promised on-demand generation, zero runtime, ultra-lightweight. As a solo developer, I longed for the "no need to write CSS class names" experience — just stack flex p-4 text-center directly in templates, no file switching, no naming headaches.

So one night I decided: map the design tokens to UnoCSS, preserving the design system while enjoying atomic writing.

III. The Collision: One Night of Struggle (With Real Config)

I wrote uno.config.ts, trying to map each --ui-* variable to an atomic class. Here's the failing configuration:

// uno.config.ts (failed version)
import { defineConfig } from 'unocss'

export default defineConfig({
  theme: {
    colors: {
      primary: 'var(--ui-primary)',
      success: 'var(--ui-success)',
      warning: 'var(--ui-warning)',
      error: 'var(--ui-error)',
      'bg-muted': 'var(--ui-bg-muted)',
      'border-subtle': 'var(--ui-border-subtle)',
      // 40+ variables need mapping...
    },
    spacing: {
      sm: 'var(--ui-spacing-sm)',
      md: 'var(--ui-spacing-md)',
      lg: 'var(--ui-spacing-lg)',
      xl: 'var(--ui-spacing-xl)',
    },
    borderRadius: {
      none: 'var(--ui-radius-none)',
      sm: 'var(--ui-radius-sm)',
      md: 'var(--ui-radius-md)',
      lg: 'var(--ui-radius-lg)',
    }
  },
  shortcuts: {
    'btn': 'px-4 py-2 rounded',
    'btn-primary': 'btn bg-primary text-white'
  }
})

Then in Button.vue, I replaced all scoped styles with atomic classes:

<!-- Button.vue after refactor (failed attempt) -->
<button :class="cn('bg-primary text-white', 'bg-bg-muted', 'border-border-subtle')">

Problems quickly emerged:

Redundant and non-semantic class names : bg-bg-muted, border-border-subtle — reads like stuttering
High mapping maintenance cost : Change a CSS variable in one place, update the UnoCSS config in another — single source of truth becomes two
Conditional logic explosion : Handling neutral color required color === 'neutral' ? 'text-dim' : 'text-'+color
Difficult debugging : Seeing bg-bg-muted in the browser means reverse-looking up which CSS variable it corresponds to
No IDE autocomplete : UnoCSS's type generation can't automatically cover my custom variable names

I deleted all mapping code that night and returned to the original solution.

IV. Epiphany: Design Tokens Are the Lightest Atomic Framework

Looking at bg-bg-muted, I suddenly asked myself: Why not just write background-color: var(--ui-bg-muted) directly?

My design token system already provides all the design constraints. The only value UnoCSS adds is "fast writing" — syntactic sugar.

Deeper still: mapping --ui-primary to bg-primary is essentially "wrapping CSS with CSS". UnoCSS generates .bg-primary { background-color: var(--ui-primary); } at compile time. If that's the final CSS, isn't writing it directly in scoped styles more straightforward?

V. Quantified Comparison: Pure Design Tokens vs UnoCSS Mapping

To objectively judge how "not worth it" it really is, I compiled this table (based on my project measurements):

Metric	Pure Design Tokens (final)	UnoCSS Mapping (abandoned)
Number of CSS variables	40+	40+ (unchanged)
Extra config file lines	0	~150 lines (`uno.config.ts`)
Class name length in templates	Short (`mg-button`)	Long (`bg-primary text-white rounded`)
Places to change one color	1 place (CSS variable definition)	2 places (CSS variable + UnoCSS mapping)
TypeScript support	None for CSS variables	Via type generation, requires extra config
Initial CSS size (gzipped)	~4 KB	~2 KB (smaller, on-demand)
Debugging experience	See `background: var(--ui-primary)` directly	Need to look up what `bg-primary` maps to
Learning curve (newcomers)	Low (just understand CSS variables)	Medium (need to understand mapping + UnoCSS rules)

Conclusion : Sacrifice ~2 KB in size for a massive reduction in maintenance cost. For a personal project, maintainability, semantic clarity, and debugging experience are more important than extreme size optimization.

VI. The Path to Harmony: Pragmatic Boundaries

My experience doesn't prove atomic CSS is bad — it proves that when your project already has a mature design token system, forcibly mapping tokens to atomic classes is redundant.

But that doesn't mean abandoning atomic tools entirely. I later found a reasonable division of labor, the key being distinguishing between "classes unrelated to values" and "classes related to values" :

Style Type	Recommended Solution	Reason
Layout (flex, grid, position)	UnoCSS atomic classes (`flex`, `grid`, `items-center`, `justify-between`, `relative`)	No values involved, no tokens needed, works out of the box
Spacing (padding, margin, gap)	*Prefer scoped styles + `var(--ui-spacing-)`**	Maintains theme consistency. If atomic classes must be used, modify UnoCSS config to map values to your tokens
Colors, border-radius, shadow, animation	Always scoped styles + CSS variables	Strong semantics, no mapping cost, intuitive debugging
Responsive variants	Can use UnoCSS `md:` prefix, but only for layout/spacing classes, never for colors	Clean and doesn't pollute design tokens

Special Note on Spacing

UnoCSS's default p-4 equals 1rem, while your design token might have --ui-spacing-md: 0.75rem. Using p-4 directly bypasses the design system. If you really want to use atomic spacing classes, you must modify the config:

// uno.config.ts (only if you want atomic spacing)
theme: {
  spacing: {
    sm: 'var(--ui-spacing-sm)',
    md: 'var(--ui-spacing-md)',
    lg: 'var(--ui-spacing-lg)',
  }
}

Then you can write p-sm, m-md. But note: this returns to the mapping maintenance problem — every time you change a token value, you must sync the UnoCSS config. I ultimately chose to completely avoid atomic spacing classes, using only valueless layout classes.

VII. When to Use Atomic CSS (If You Don't Have Design Tokens)

I'm not an opponent of atomic CSS. I would not hesitate to choose UnoCSS/Tailwind if:

✅ New project, rapid prototyping
✅ Design system not yet mature, still iterating quickly
✅ Entire team familiar with atomic syntax
✅ No need to reuse styles across frameworks

Scenarios to avoid :

❌ Existing mature design tokens requiring long-term maintenance
❌ Need to reuse style files across Vue/React/Svelte
❌ CSS size is not the primary concern (modern atomic frameworks are actually quite small)

VIII. Advice for Developers in the Same Situation

If you're like me — already have a complete design token system (CSS variables, Design Tokens) but want to try atomic CSS — my advice:

Don't map core tokens like colors, theme spacing, border-radius. Use them directly via var(--ui-*) in scoped styles.
Only use the generic layout classes provided by atomic tools (flex, grid, items-center, relative...). These have nothing to do with your design system and require no mapping.
Beware of "magic numbers" : Avoid hardcoded values like p-3.5 or gap-11 in templates — they break the design token contract.
For responsive layouts , continue using atomic tools' responsive variants (md:flex), but try to use them only for layout, never for colors/spacing.
If atomic tools feel like "using for the sake of using", you can completely abandon them. Native CSS + design tokens is already clear and maintainable enough.

IX. Looking Ahead: DTCG and the Future

The W3C Design Tokens Community Group (DTCG) released its first stable specification at the end of 2025, advancing design tokens as a cross-platform common language. This means the token-centric architecture is becoming industry consensus.

Atomic tools can consume design tokens, but shouldn't hijack them. Hardcoding tokens into tool-specific atomic classes locks your design system into that tool's syntax. Using CSS variables directly, on the other hand, is framework-agnostic and future-oriented.

In the future, when DTCG tooling matures, it may automatically generate atomic classes from design tokens. At that point I'll reevaluate UnoCSS. But for now (2026), manual mapping is still a maintenance burden.

X. Conclusion: Design Tokens First, Atomic Optional

In the end, my Button.vue went back to its original form:

<style scoped>
.mg-button {
  background-color: var(--ui-primary);
  color: white;
  padding: var(--ui-spacing-md) var(--ui-spacing-lg);
}
</style>

Simple, direct, semantic. That's how design tokens should be used.

UnoCSS and Tailwind are good tools, but they're not substitutes for a design system. Design tokens are the foundation; atomic is just a layer of paint on top. When you already have a solid foundation, whether to apply that layer of paint depends on whether you're willing to accept the maintenance cost for some syntactic sugar.

For me, at least, it's not worth it.

The original Chinese version is available on my blog: moongate.top.

Try the component library on npm: moongate-vue

Explore the component documentation: vue.moongate.top

Brand Ecosystem: Design Philosophy & Visual Contract

yuelinghuashu — Sun, 12 Apr 2026 13:55:58 +0000

Introduction: From Engineering to Design System

Through the first four articles, we built Moongate's engineering foundation step by step: from handwritten JSON to modular YAML, from the DTCG three-layer architecture to a testable industrial-grade build system. By now we have an efficient, extensible, self-validating theme production system.

But a truly great theme is not just a collection of color rules — it is a complete design system: a clear design philosophy, a reusable visual language, a contract for communicating with users, and a brand ecosystem that can be reused across platforms.

This article completes the final leap: from "engineering" to "design system". You will see how the engineering capabilities built in the first four articles (DTCG tokens, build artifacts, automated validation) support a brand ecosystem that can be reused across platforms.

Part 1: Design Philosophy — Giving Every Color a Meaning

Any design system must stand on a clear design philosophy. Without philosophy, colors are just random combinations; with philosophy, colors become brand recognition.

1.1 Cool Base: Eliminating Visual Dirt

General principle: add a subtle cool tint (blue or green) to backgrounds, borders, and grays, avoiding the visual "dirt" of pure black or pure white. Pure black makes highlight colors "bleed and glow", while pure white tends to look yellowed and grayish. A touch of coolness keeps the base clean and deep, letting the colorful semantic colors on top appear more purely.

Moongate example:

Dark background: #0f172a (deep-space blue-black)
Light background: #f9fafb (cool moon white)

1.2 Semantic Layering: A Three-Level Staircase of Information

General principle: code is not flat — it naturally has hierarchy. Divide all code elements into three visual levels — foreground (core logic), midground (ordinary code), background (auxiliary information) — distinguished by contrast, saturation, and font styles (bold, italic, etc.), letting the code structure surface by itself.

Moongate example:

Level	Role	Visual traits	Examples
Foreground	Core logic	High contrast, bold, or high saturation	Keywords, function definitions, class names
Midground	Ordinary code	Medium contrast, visually natural	Variables, strings, numbers
Background	Auxiliary info	Muted but readable	Comments, punctuation, operators

This layering runs through all languages and all theme variants — it is the underlying guarantee of Moongate's visual consistency.

1.3 Gravity Compensation: Visual Weight Parity Across Day and Night

General principle: a light theme is not a simple inversion of a dark theme. Bright colors on dark backgrounds are "emitters"; dark colors on light backgrounds are "absorbents". To give the same semantic role equal visual weight on different backgrounds, you must keep the hue unchanged while scientifically adjusting lightness and saturation. This is called gravity compensation.

Moongate example:

Semantic role	Dark version	Light version	Adjustment method
Primary	`#3b82f6` (60% L)	`#0284c7` (48% L)	Hue unchanged, lightness down ~20%
Success	`#34d399` (65%)	`#059669` (40%)	Lightness down, saturation slightly down
Warning	`#fbbf24` (75%)	`#b45309` (35%)	Bright yellow to amber, avoids disappearing on white
Error	`#f87171` (60%)	`#b91c1c` (35%)	Deep red keeps its warning feel

When users switch themes, the visual weight of the same syntax element stays almost unchanged — no relearning needed.

1.4 Elevation System: Physical Depth for the UI

General principle: express physical depth by defining a staircase of background lightness. In dark mode, the higher the surface, the brighter it is (lightness increases); in light mode, the higher the surface, the brighter it is too (but using brighter whites/light grays). The step size stays consistent, forming a smooth sense of layering.

Moongate example (latest values in v2.6.0):

Elevation level	Purpose	Dark mode	Light mode	Brightness change
`surfaceGround`	Base background	`#0f172a`	`#f9fafb`	Base level
`surfaceRaised`	Sidebar, activity bar	`#1a2538`	`#ffffff`	dark +5%, light pure white
`surfaceFloating`	Panels, floating cards	`#25364a`	`#f1f5f9`	dark another +5%, light cool light gray
`surfaceTooltip`	Tooltips, popups	`#2e3b4d`	`#e2e8f0`	Highest level

This makes the sidebar gently raised, floating panels lightly elevated, and the code area deep and calm — the editor moves from flat to three-dimensional, and the physical metaphor makes the UI hierarchy obvious at a glance.

Part 2: Visual Contract — Connecting Users and Hardware

General principle: no matter how well a theme is designed, if the user's monitor is not calibrated, the result suffers. Provide a monitor calibration guide (visual contract) that helps users adjust Gamma, brightness, contrast, and color temperature, and reminds them to turn off "enhancement" features such as dynamic contrast and vivid mode. The end of calibration is not theoretical perfection, but the balance point where the user feels most comfortable.

Moongate example: extras/VISUAL_CONTRACT.md provides the detailed Visual Contract document (v2.0), with these core steps:

Step	Action	Goal
1. Set Gamma	Choose `Gamma 2.2`	Smooth grayscale transitions
2. Adjust brightness	Dark mode: make the 2% gray block just visible; light mode: make blocks 250–255 clearly distinguishable	Preserve shadow/highlight detail
3. Adjust contrast	The 100% white block should be clear but not harsh	Avoid overexposure
4. Color temperature	Recommend `6500K` or `warm` mode	Neutralize blue light

v2.0 especially emphasizes mode-specific calibration:

Dark mode (night environment): in a dark room, adjust brightness until the Black level test page shows the 2% gray block as just discernible.
Light mode (day environment): under typical lighting, use the White saturation test page so that blocks 250–255 are clearly distinguishable and the 255 pure white is not harsh.

It also lists common monitor pitfalls and their fixes:

Pitfall	Symptom	Fix
Black stabilizer	Dark background looks gray, dark text fades	Lock at 50 or turn off
Vivid mode / wide gamut	Colors drift, cool tones warm up	Prefer sRGB mode
Oversharpening	"Ghosting" around character edges	Lower to 50–60

💡 Why is the visual contract a "contract" rather than a "tutorial"? Because it is not about teaching users how to calibrate a monitor — it is a mutual agreement: the theme developer promises "the colors are carefully designed", and the user promises "the design is faithfully presented through reasonable calibration". This contract makes the theme's behavior across different hardware controllable and predictable.

🚀 Quick version: 3 steps of "good enough"

Full calibration is valuable for users who chase precision, but if you would rather not fiddle with hardware parameters, these 3 steps give a good-enough experience:

Pick the right mode: switch the monitor to sRGB / Standard, and turn off "enhancement" features such as Dynamic Contrast, Vivid Mode, and Black Stabilizer — this alone solves 80% of color drift.
Tune by eye: if dark mode looks grayish or light-mode text is harsh, nudge brightness until it feels comfortable.
Set the color temperature floor: choose 6500K or Warm to neutralize blue light.

There is no need for Gamma curves and test blocks at hardware-grade precision — "comfortable to the eye" is the first standard. When you want finer results, follow the full steps above.

Part 3: Brand Ecosystem — From Theme to Community

General principle: a complete brand system includes a documentation system (README, CHANGELOG, design docs), community interaction (open source, feedback channel---
title: "Industrial‑Grade Build Scripts & DTCG Implementation"
description: "Implement an industrial‑grade build script with DTCG three‑layer architecture, color normalization, WCAG contrast checking, circular reference detection, and automatic generation of CSS variables and design system documentation."
tags: [vscode, theme, engineering, design]
series: VS Code Theme Development Guide

canonical_url: https://moongate.top/docs/create-vscode-theme-engineering-deep

🚀 Introduction

In Part 4, we introduced the DTCG three‑layer architecture for design tokens and the concept of industrial‑grade quality checks. This part will turn those concepts into runnable engineering code, presenting the complete industrial‑grade build script of Moongate v2.2.0.

If you have already completed the basic build script from Part 2 and want to upgrade to an industrial level – supporting color normalization, WCAG contrast checking, circular reference detection, and automatic generation of CSS variables and design system documentation – then this part is for you.

💡 Note: This part involves advanced engineering practices. It is recommended to read the first three parts (Basics, Engineering, Multi‑theme) first.

📁 Directory Structure

your-theme/
├── src/
│   ├── core/
│   │   ├── primitives/
│   │   │   └── colors.yaml          # Raw color values
│   │   ├── semantics/
│   │   │   ├── dark.yaml            # Dark semantic layer
│   │   │   └── light.yaml           # Light semantic layer
│   │   └── layout.yaml              # Layout tokens (spacing, typography, breakpoints, etc.)
│   ├── languages/                   # Syntax rules per language
│   ├── workbench.yaml               # UI colors
│   └── semantic.yaml                # Semantic highlighting rules
├── scripts/
│   └── build.js                     # Industrial‑grade build script
├── themes/
│   ├── moongate-dark.json           # Generated theme JSON
│   ├── moongate-light.json
│   ├── moongate-colors.css          # Color tokens (auto‑generated)
│   └── moongate-layout.css          # Layout tokens (auto‑generated)
├── docs/
│   └── DESIGN_SYSTEM.md             # Auto‑generated design system documentation
└── package.json

🎨 Step 1: Primitives File

src/core/primitives/colors.yaml

View full primitives file

# ==================== Raw color values ====================
# Named by hue‑lightness, used as the basic building blocks for all themes

# Blue
blue-500: "#3b82f6"
blue-600: "#2563eb"
blue-700: "#0284c7"
blue-800: "#0369a1"
blue-900: "#1e3a8a"
blue-glow: "#7dd3fc"
blue-glow-dark: "#87cefa"

# Green
green-400: "#34d399"
green-600: "#059669"
green-700: "#10b981"

# Yellow
yellow-400: "#fbbf24"
yellow-500: "#f59e0b"
yellow-600: "#d97706"
yellow-700: "#b45309"

# Red
red-400: "#f87171"
red-500: "#ef4444"
red-600: "#dc2626"
red-700: "#b91c1c"

# Cyan
cyan-400: "#22d3ee"
cyan-500: "#0891b2"
cyan-700: "#0e7490"

# Purple
purple-400: "#c084fc"
purple-500: "#9333ea"
purple-700: "#7e22ce"

# Grayscale
gray-900: "#0f172a"
gray-850: "#131c31"
gray-800: "#1e293b"
gray-750: "#252e40"
gray-700: "#2d3748"
gray-600: "#475569"
gray-550: "#7a8c9e"
gray-500: "#94a3b8"
gray-525: "#a5b4cb"
gray-400: "#94a3b8"
gray-300: "#cbd5e1"
gray-200: "#e2e8f0"
gray-100: "#f1f5f9"
gray-50: "#f9fafb"

# Pure
white: "#ffffff"
black: "#000000"

🌙 Step 2: Semantic Layer Files

Dark Semantic Layer `src/core/semantics/dark.yaml`

View full dark semantic layer

# ==================== Dark semantic layer ====================

primary: "{blue-500}"
success: "{green-400}"
warning: "{yellow-400}"
error: "{red-400}"
highlight: "{blue-glow}"
cyan: "{cyan-400}"
purple: "{purple-400}"

function: "{blue-glow-dark}"
operator: "{gray-600}"
comment: "{gray-525}"
variable: "{gray-200}"
variableDim: "{gray-300}"
textMuted: "{gray-400}"
punctuation: "{gray-400}"

bg: "{gray-900}"
bgElevated: "{gray-850}"
bgMuted: "{gray-800}"
bgHover: "{blue-500}20"
bgActive: "{blue-500}40"
hoverBg: "{gray-750}"
selectedBg: "{blue-600}"

surfaceGround: "{gray-900}"
surfaceRaised: "{gray-850}"
surfaceFloating: "{gray-800}"
surfaceTooltip: "{gray-750}"
borderFloating: "{blue-500}40"

text: "{gray-200}"
textDim: "{gray-300}"
textInactive: "{gray-400}"

border: "{gray-700}"
borderHover: "{blue-500}"
borderDim: "{gray-600}"

buttonHoverBg: "{blue-600}"
white: "{white}"

ansiBlack: "{gray-800}"
ansiRed: "{red-400}"
ansiGreen: "{green-400}"
ansiYellow: "{yellow-400}"
ansiBlue: "{blue-500}"
ansiMagenta: "{purple-400}"
ansiCyan: "{cyan-400}"
ansiWhite: "{gray-200}"
ansiBrightBlack: "{gray-700}"
ansiBrightRed: "{red-400}"
ansiBrightGreen: "{green-400}"
ansiBrightYellow: "{yellow-400}"
ansiBrightBlue: "{blue-500}"
ansiBrightMagenta: "{purple-400}"
ansiBrightCyan: "{cyan-400}"
ansiBrightWhite: "{white}"

bracket1: "{blue-glow}"
bracket2: "{green-400}"
bracket3: "{yellow-400}"
bracket4: "{purple-400}"
bracket5: "{blue-500}"
bracket6: "{gray-400}"

scrollbar: "{blue-500}"
gitAdded: "{green-400}"
gitModified: "{yellow-400}"
gitDeleted: "{red-400}"
gitUntracked: "{gray-400}"
gitIgnored: "{gray-700}"
debugStart: "{green-400}"
debugPause: "{yellow-400}"
debugStop: "{red-400}"

Light Semantic Layer `src/core/semantics/light.yaml`

View full light semantic layer

# ==================== Light semantic layer ====================

primary: "{blue-700}"
success: "{green-600}"
warning: "{yellow-700}"
error: "{red-700}"
highlight: "{blue-800}"
cyan: "{cyan-700}"
purple: "{purple-700}"

function: "{blue-800}"
operator: "{gray-600}"
comment: "{gray-600}"
variable: "{gray-900}"
variableDim: "{gray-600}"
textMuted: "{gray-600}"
punctuation: "{gray-400}"

bg: "{gray-50}"
bgElevated: "{white}"
bgMuted: "{gray-100}"
bgHover: "{blue-700}15"
bgActive: "{blue-700}25"
hoverBg: "{gray-100}"
selectedBg: "{gray-300}"

surfaceGround: "{gray-50}"
surfaceRaised: "{white}"
surfaceFloating: "{gray-100}"
surfaceTooltip: "{gray-200}"
borderFloating: "{blue-700}80"

text: "{gray-900}"
textDim: "{gray-600}"
textInactive: "{gray-400}"

border: "{gray-300}"
borderHover: "{blue-700}"
borderDim: "{gray-400}"

buttonHoverBg: "{blue-700}"
white: "{white}"

ansiBlack: "{gray-900}"
ansiRed: "{red-700}"
ansiGreen: "{green-600}"
ansiYellow: "{yellow-700}"
ansiBlue: "{blue-700}"
ansiMagenta: "{purple-700}"
ansiCyan: "{cyan-700}"
ansiWhite: "{gray-200}"
ansiBrightBlack: "{gray-500}"
ansiBrightRed: "{red-400}"
ansiBrightGreen: "{green-400}"
ansiBrightYellow: "{yellow-400}"
ansiBrightBlue: "{blue-600}"
ansiBrightMagenta: "{purple-400}"
ansiBrightCyan: "{cyan-400}"
ansiBrightWhite: "{white}"

bracket1: "{blue-700}"
bracket2: "{green-600}"
bracket3: "{yellow-700}"
bracket4: "{purple-700}"
bracket5: "{cyan-700}"
bracket6: "{gray-500}"

scrollbar: "{blue-700}"
gitAdded: "{green-600}"
gitModified: "{yellow-700}"
gitDeleted: "{red-700}"
gitUntracked: "{gray-500}"
gitIgnored: "{gray-400}"
debugStart: "{green-600}"
debugPause: "{yellow-700}"
debugStop: "{red-700}"

📐 Step 3: Layout Tokens File

src/core/layout.yaml

View full layout tokens file

# ==================== Layout tokens ====================
# Spacing, radius, shadow, typography, breakpoints, z‑index

spacing:
  base: "4px"
  xs: "4px"
  sm: "8px"
  md: "16px"
  lg: "24px"
  xl: "32px"
  "2xl": "48px"

radius:
  none: "0px"
  sm: "0px"
  md: "0px"
  lg: "0px"

shadow:
  none: "none"
  border: "0 0 0 1px"

typography:
  family-mono: "'JetBrains Mono', 'Fira Code', monospace"
  family-sans: "Inter, system-ui, -apple-system, sans-serif"
  size-code: "13px"
  size-body: "14px"
  size-small: "12px"
  line-height: "1.5"

breakpoints:
  mobile: "640px"
  tablet: "768px"
  desktop: "1024px"
  wide: "1280px"

z-index:
  base: 1
  sticky: 100
  overlay: 500
  modal: 1000
  tooltip: 1500

🛠️ Step 4: Industrial‑Grade Build Script

scripts/build.js

View full industrial‑grade build script

const fs = require("fs");
const yaml = require("js-yaml");
const path = require("path");
const wcag = require("wcag-contrast");

const ROOT_DIR = path.resolve(__dirname, "..");

// ==================== Path Configuration ====================
const PATHS = {
  primitives: path.join(ROOT_DIR, "src", "core", "primitives", "colors.yaml"),
  semanticsDir: path.join(ROOT_DIR, "src", "core", "semantics"),
  layout: path.join(ROOT_DIR, "src", "core", "layout.yaml"),
  workbench: path.join(ROOT_DIR, "src", "workbench.yaml"),
  semantic: path.join(ROOT_DIR, "src", "semantic.yaml"),
  langDir: path.join(ROOT_DIR, "src", "languages"),
  specialDir: path.join(ROOT_DIR, "src", "special"),
  outputDir: path.join(ROOT_DIR, "themes"),
  docsDir: path.join(ROOT_DIR, "docs"),
};

// ==================== Helper Functions ====================

function ensureFileExists(filePath, description) {
  if (!fs.existsSync(filePath)) {
    throw new Error(`❌ ${description} file not found: ${filePath}`);
  }
}

function safeLoadYaml(filePath, description) {
  try {
    return yaml.load(fs.readFileSync(filePath, "utf8"));
  } catch (err) {
    console.error(`❌ Failed to parse ${description} (${filePath}):`, err.message);
    return null;
  }
}

/**
 * Normalize hex color
 */
function normalizeHex(color, tokenName) {
  if (typeof color !== "string" || !color.startsWith("#")) {
    if (color && !color.startsWith("#")) {
      console.warn(`⚠️ Skipping non‑hex color: ${tokenName} = ${color}`);
    }
    return color;
  }

  let hex = color.replace("#", "");

  if (hex.length === 3) {
    hex = hex.split("").map((c) => c + c).join("");
  } else if (hex.length === 4) {
    hex = hex.split("").map((c) => c + c).join("");
  }

  if (!/^[0-9a-fA-F]{6}$|^[0-9a-fA-F]{8}$/.test(hex)) {
    console.error(`❌ Fatal error: token "${tokenName}" value "${color}" does not conform to industrial specification.`);
    console.error(`   Requirement: 6‑digit (#RRGGBB) or 8‑digit (#RRGGBBAA) hex`);
    process.exit(1);
  }

  return `#${hex.toLowerCase()}`;
}

/**
 * Recursively resolve token references {token-name}
 */
function resolveTokens(obj, tokenMap, depth = 0, path = []) {
  const MAX_DEPTH = 20;
  if (depth > MAX_DEPTH) {
    throw new Error(`[ENGINEERING_FATAL] Circular reference detected: ${path.join(" → ")}`);
  }

  if (typeof obj === "string") {
    const resolveOne = (str) => {
      return str.replace(/\{([a-zA-Z0-9_-]+)\}/g, (match, key) => {
        const value = tokenMap[key];
        if (value === undefined) {
          console.warn(`⚠️ Warning: token "${key}" not defined, keeping placeholder`);
          return match;
        }
        return resolveOne(value);
      });
    };
    return resolveOne(obj);
  }
  if (Array.isArray(obj)) {
    return obj.map((item) => resolveTokens(item, tokenMap, depth + 1, path));
  }
  if (obj && typeof obj === "object") {
    const result = {};
    for (const [k, v] of Object.entries(obj)) {
      result[k] = resolveTokens(v, tokenMap, depth + 1, [...path, k]);
    }
    return result;
  }
  return obj;
}

/**
 * Normalize all color values
 */
function normalizeColors(obj, tokenName) {
  if (typeof obj === "string") {
    return normalizeHex(obj, tokenName);
  }
  if (Array.isArray(obj)) {
    return obj.map((item) => normalizeColors(item, tokenName));
  }
  if (obj && typeof obj === "object") {
    const result = {};
    for (const [k, v] of Object.entries(obj)) {
      result[k] = normalizeColors(v, `${tokenName}.${k}`);
    }
    return result;
  }
  return obj;
}

/**
 * Detect direct primitive references (e.g., {blue-500})
 */
function detectPrimitiveReference(value, context) {
  if (typeof value === "string" && /\{([a-zA-Z0-9_-]+)\}/.test(value)) {
    const match = value.match(/\{([a-zA-Z0-9_-]+)\}/)[1];
    const primitivePrefixes = [
      "blue-", "green-", "yellow-", "red-", "cyan-", "purple-", "gray-",
      "white", "black",
    ];
    if (primitivePrefixes.some((prefix) => match.startsWith(prefix))) {
      console.warn(`[Architecture reminder] ${context} directly references primitive value "${match}". Use semantic layer instead.`);
    }
  }
}

/**
 * Replace ${var} with final color value (supports opacity suffix)
 * Opacity suffix format: two‑digit hex (00–FF), e.g., 20 ≈ 12.5% opacity, 80 ≈ 50%, FF = opaque.
 */
function replaceVariables(obj, colors, context = "") {
  if (typeof obj === "string") {
    if (context) detectPrimitiveReference(obj, context);

    return obj.replace(/\$\{([a-zA-Z0-9_-]+)\}([0-9a-fA-F]{2})?/g, (match, key, alpha) => {
      const value = colors[key];
      if (value === undefined) {
        console.warn(`⚠️ Warning: variable "${key}" not defined, keeping placeholder`);
        return match;
      }
      if (alpha) {
        if (/^rgba?\(/.test(value)) {
          console.warn(`⚠️ Warning: variable "${key}" value ${value} is already rgba, ignoring suffix`);
          return value;
        }
        if (/^#[0-9a-fA-F]{8}$/.test(value)) {
          console.warn(`⚠️ Warning: variable "${key}" value ${value} already contains opacity, ignoring suffix "${alpha}"`);
          return value;
        }
        if (/^#[0-9a-fA-F]{6}$/.test(value)) {
          return value + alpha;
        }
        console.warn(`⚠️ Warning: variable "${key}" value ${value} has unsupported format, cannot apply opacity`);
        return value;
      }
      return value;
    });
  }
  if (Array.isArray(obj)) {
    return obj.map((item) => replaceVariables(item, colors, context));
  }
  if (obj && typeof obj === "object") {
    const result = {};
    for (const [k, v] of Object.entries(obj)) {
      result[k] = replaceVariables(v, colors, context);
    }
    return result;
  }
  return obj;
}

/**
 * WCAG contrast check (graduated standard)
 */
function checkContrast(color1, color2, role, themeType) {
  if (!color1 || !color2) return;
  const ratio = wcag.hex(color1, color2);

  let minRatio = 4.5;
  if (role === "textDim" || role === "comment") {
    minRatio = 4.0;
  }
  if (role === "textMuted") {
    minRatio = 3.0;
  }

  if (ratio < minRatio) {
    if (role === "textMuted") {
      console.warn(`⚠️ Contrast slightly low: ${themeType} · ${role} (${color1}) vs background (${color2}) = ${ratio.toFixed(2)}:1`);
      console.warn(`   Recommended ≥3.0:1, currently meets minimum.`);
    } else {
      console.error(`❌ Insufficient contrast: ${themeType} · ${role} (${color1}) vs background (${color2}) = ${ratio.toFixed(2)}:1`);
      console.error(`   WCAG requires ≥${minRatio}:1, below standard.`);
      process.exit(1);
    }
  } else {
    console.log(`✅ ${themeType} · ${role}: ${ratio.toFixed(2)}:1`);
  }
}

/**
 * Generate CSS variables for colors (includes light/dark mode)
 */
function generateColorCss(lightColors, darkColors) {
  let css = `/* ===== Moongate Color Tokens – Auto‑generated ===== */\n`;
  css += `/* Source: VS Code theme build script */\n`;
  css += `/* Do not edit manually – edit primitives/ and semantics/ directories instead */\n\n`;

  css += `/* Light mode */\n:root,\n.light {\n`;
  Object.entries(lightColors).forEach(([key, val]) => {
    const cssKey = key.replace(/([A-Z])/g, "-$1").toLowerCase();
    css += `  --ui-${cssKey}: ${val};\n`;
  });
  css += `}\n\n`;

  css += `/* Dark mode */\n.dark {\n`;
  Object.entries(darkColors).forEach(([key, val]) => {
    const cssKey = key.replace(/([A-Z])/g, "-$1").toLowerCase();
    css += `  --ui-${cssKey}: ${val};\n`;
  });
  css += `}\n`;

  const cssPath = path.join(PATHS.outputDir, "moongate-colors.css");
  fs.writeFileSync(cssPath, css);
  console.log(`✅ Color tokens generated: ${cssPath}`);
}

/**
 * Generate CSS variables for layout tokens (supports nested objects)
 */
function generateLayoutCss(layoutTokens) {
  let css = `/* ===== Moongate Layout Tokens – Auto‑generated ===== */\n`;
  css += `/* Includes: spacing, radius, shadow, typography, breakpoints, z‑index */\n`;
  css += `/* Do not edit manually – edit src/core/layout.yaml instead */\n\n`;

  css += `:root {\n`;

  function flattenObject(obj, prefix = "") {
    Object.entries(obj).forEach(([key, val]) => {
      const fullKey = prefix ? `${prefix}-${key}` : key;
      if (val && typeof val === "object" && !Array.isArray(val)) {
        flattenObject(val, fullKey);
      } else {
        let formattedVal = val;
        if (typeof formattedVal === "string") {
          if ((formattedVal.startsWith("'") && formattedVal.endsWith("'")) ||
              (formattedVal.startsWith('"') && formattedVal.endsWith('"'))) {
            formattedVal = formattedVal.slice(1, -1);
          }
        }
        css += `  --ui-${fullKey}: ${formattedVal};\n`;
      }
    });
  }

  flattenObject(layoutTokens);

  css += `}\n`;

  const cssPath = path.join(PATHS.outputDir, "moongate-layout.css");
  fs.writeFileSync(cssPath, css);
  console.log(`✅ Layout tokens generated: ${cssPath}`);
}

/**
 * Generate design system documentation (enhanced)
 * Includes variable selection protocol, primitive colors, elevation system, semantic layer contrast
 */
function generateDesignSystemDoc(primitives, lightColors, darkColors) {
  const md = [];

  md.push("# Moongate Design System\n");
  md.push("## 🧭 Moongate Variable Selection Protocol\n");
  md.push("To ensure long‑term maintainability and semantic consistency, follow this decision path:\n");
  md.push("| Scenario | Lookup Location | Prohibited Action |");
  md.push("|----------|----------------|-------------------|");
  md.push("| **I need to define a new primitive color** (e.g., `blue-600`) | `primitives/colors.yaml` | ❌ Do not write raw color values in semantics or components |");
  md.push("| **I need to assign a value to a semantic role** (e.g., `primary`) | `semantics/*.yaml` (reference primitives) | ❌ Do not reference primitives directly in components |");
  md.push("| **I need to style a UI component** (e.g., `sideBar.background`) | Reference semantic variables (e.g., `${surfaceRaised}`) | ❌ Do not use `${blue-500}` directly or hard‑code colors |");
  md.push("| **I need a new semantic role** | Add a logical role in semantics (e.g., `actionHover`), then reference it in components | ❌ Never invent new variables inside components |");
  md.push("\n> **Core principle**: All colors must flow through the chain `primitives → semantics → components`. Any cross‑layer direct reference is **architecture pollution**.\n");

  md.push("## 🎨 Primitive Colors\n");

  const colorGroups = {
    blue: ["blue-500", "blue-600", "blue-700", "blue-800", "blue-900", "blue-glow", "blue-glow-dark"],
    green: ["green-400", "green-600", "green-700"],
    yellow: ["yellow-400", "yellow-500", "yellow-600", "yellow-700"],
    red: ["red-400", "red-500", "red-600", "red-700"],
    cyan: ["cyan-400", "cyan-500", "cyan-700"],
    purple: ["purple-400", "purple-500", "purple-700"],
    gray: Object.keys(primitives).filter((k) => k.startsWith("gray-")),
    special: ["white", "black"],
  };

  for (const [group, keys] of Object.entries(colorGroups)) {
    if (keys.length === 0) continue;
    md.push(`### ${group.charAt(0).toUpperCase() + group.slice(1)} Series\n`);
    md.push("| Token | Value | Preview |");
    md.push("|-------|-------|---------|");
    for (const key of keys) {
      if (!primitives[key]) continue;
      const val = primitives[key];
      const preview = `![](https://placehold.co/20x20/${val.slice(1)}/${val.slice(1)}?text=+)`;
      md.push(`| \`--moongate-${key}\` | \`${val}\` | ${preview} |`);
    }
    md.push("");
  }

  md.push("## 🏔️ Elevation System\n");
  md.push("The elevation system expresses physical depth through lightness differences, following Material Design elevation guidelines.\n");
  md.push("| Variable | Light Mode | Dark Mode | Description |");
  md.push("|----------|------------|-----------|-------------|");
  md.push(`| \`surfaceGround\` | \`${lightColors.surfaceGround}\` | \`${darkColors.surfaceGround}\` | Ground layer (0dp) – editor background |`);
  md.push(`| \`surfaceRaised\` | \`${lightColors.surfaceRaised}\` | \`${darkColors.surfaceRaised}\` | Raised layer (2dp) – sidebar, activity bar |`);
  md.push(`| \`surfaceFloating\` | \`${lightColors.surfaceFloating}\` | \`${darkColors.surfaceFloating}\` | Floating layer (8dp) – popups, menus |`);
  md.push(`| \`surfaceTooltip\` | \`${lightColors.surfaceTooltip}\` | \`${darkColors.surfaceTooltip}\` | Tooltip layer (12dp) – tooltips |`);
  md.push(`| \`borderFloating\` | \`${lightColors.borderFloating}\` | \`${darkColors.borderFloating}\` | Floating layer border (translucent primary) |\n`);

  const contrast = (color1, color2) => {
    if (!color1 || !color2) return null;
    try {
      return wcag.hex(color1, color2).toFixed(2);
    } catch {
      return null;
    }
  };

  md.push("## 🌙 Light Mode Semantics\n");
  md.push("| Semantic Variable | Value | Preview | WCAG Contrast (vs `bg`) |");
  md.push("|------------------|-------|---------|--------------------------|");
  const lightBg = lightColors.bg;
  const importantKeys = ["text", "textDim", "textMuted", "comment", "primary", "success", "warning", "error"];
  for (const [key, val] of Object.entries(lightColors)) {
    const preview = `![](https://placehold.co/20x20/${val.slice(1)}/${val.slice(1)}?text=+)`;
    let contrastRatio = "-";
    if (importantKeys.includes(key) && lightBg) {
      const ratio = contrast(val, lightBg);
      if (ratio) contrastRatio = `${ratio}:1`;
    }
    md.push(`| \`${key}\` | \`${val}\` | ${preview} | ${contrastRatio} |`);
  }

  md.push("\n## 🌑 Dark Mode Semantics\n");
  md.push("| Semantic Variable | Value | Preview | WCAG Contrast (vs `bg`) |");
  md.push("|------------------|-------|---------|--------------------------|");
  const darkBg = darkColors.bg;
  for (const [key, val] of Object.entries(darkColors)) {
    const preview = `![](https://placehold.co/20x20/${val.slice(1)}/${val.slice(1)}?text=+)`;
    let contrastRatio = "-";
    if (importantKeys.includes(key) && darkBg) {
      const ratio = contrast(val, darkBg);
      if (ratio) contrastRatio = `${ratio}:1`;
    }
    md.push(`| \`${key}\` | \`${val}\` | ${preview} | ${contrastRatio} |`);
  }

  const mdPath = path.join(PATHS.docsDir, "DESIGN_SYSTEM.md");
  if (!fs.existsSync(PATHS.docsDir)) {
    fs.mkdirSync(PATHS.docsDir, { recursive: true });
  }
  fs.writeFileSync(mdPath, md.join("\n"), "utf8");
  console.log(`✅ Design system documentation generated: ${mdPath}`);
}

function getThemeInfo() {
  const pkgPath = path.join(ROOT_DIR, "package.json");
  if (!fs.existsSync(pkgPath)) {
    return { name: "your-theme", displayName: "Your Theme" };
  }
  try {
    const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
    let displayName = pkg.displayName || pkg.name || "Your Theme";
    if (displayName.startsWith("@") && displayName.includes("/")) {
      displayName = displayName.split("/")[1];
    }
    return {
      name: pkg.name || "your-theme",
      displayName,
    };
  } catch {
    return { name: "your-theme", displayName: "Your Theme" };
  }
}

// ==================== Main ====================
function main() {
  console.log("🚀 Building theme (DTCG standard + industrial quality checks)...\n");

  try {
    ensureFileExists(PATHS.primitives, "primitives");
    ensureFileExists(PATHS.semanticsDir, "semantics directory");
    ensureFileExists(PATHS.layout, "layout tokens");
    ensureFileExists(PATHS.workbench, "workbench");
    ensureFileExists(PATHS.semantic, "semantic");
  } catch (err) {
    console.error(err.message);
    process.exit(1);
  }

  console.log("📦 Loading primitives...");
  const primitivesRaw = safeLoadYaml(PATHS.primitives, "primitives.yaml");
  if (!primitivesRaw) process.exit(1);

  const primitives = {};
  Object.entries(primitivesRaw).forEach(([key, val]) => {
    primitives[key] = normalizeHex(val, `primitives.${key}`);
  });

  console.log("📦 Loading layout tokens...");
  const layoutTokens = safeLoadYaml(PATHS.layout, "layout.yaml");
  if (layoutTokens) {
    generateLayoutCss(layoutTokens);
  } else {
    console.error("❌ Failed to load layout.yaml, build aborted");
    process.exit(1);
  }

  console.log("📦 Loading shared rules...");
  const workbenchRaw = safeLoadYaml(PATHS.workbench, "workbench.yaml");
  const semanticRaw = safeLoadYaml(PATHS.semantic, "semantic.yaml");
  if (!workbenchRaw || !semanticRaw) process.exit(1);

  console.log("📚 Loading language rules...");
  let tokenColorsRaw = [];
  if (fs.existsSync(PATHS.langDir)) {
    const langFiles = fs.readdirSync(PATHS.langDir).filter((f) => f.endsWith(".yaml")).sort();
    langFiles.forEach((file) => {
      const filePath = path.join(PATHS.langDir, file);
      const langRules = safeLoadYaml(filePath, `language rules ${file}`);
      if (langRules?.tokenColors) {
        tokenColorsRaw = tokenColorsRaw.concat(langRules.tokenColors);
        console.log(`   ✅ Loaded: ${file}`);
      }
    });
  }

  console.log("✨ Loading special rules...");
  if (fs.existsSync(PATHS.specialDir)) {
    const specialFiles = fs.readdirSync(PATHS.specialDir).filter((f) => f.endsWith(".yaml"));
    specialFiles.forEach((file) => {
      const filePath = path.join(PATHS.specialDir, file);
      const specialRules = safeLoadYaml(filePath, `special rules ${file}`);
      if (specialRules?.tokenColors) {
        tokenColorsRaw = tokenColorsRaw.concat(specialRules.tokenColors);
        console.log(`   ✅ Loaded: ${file}`);
      }
    });
  }

  console.log("\n🎨 Scanning semantic files...");
  const semanticFiles = fs.readdirSync(PATHS.semanticsDir).filter((f) => f.endsWith(".yaml"));
  if (semanticFiles.length === 0) {
    console.error("❌ No .yaml files found in semantics directory");
    process.exit(1);
  }

  const themeInfo = getThemeInfo();
  let baseName = themeInfo.name.replace(/[^a-z0-9-]/gi, "-").toLowerCase();

  let lightSemantics, darkSemantics;

  console.log(`\n🔨 Building themes...\n`);
  semanticFiles.forEach((semanticFile) => {
    const themeType = path.basename(semanticFile, ".yaml");
    const outputFile = path.join(PATHS.outputDir, `${baseName}-${themeType}.json`);

    const semanticsPath = path.join(PATHS.semanticsDir, semanticFile);
    const semantics = safeLoadYaml(semanticsPath, `semantic layer ${semanticFile}`);
    if (!semantics) {
      console.error(`   ❌ Skipping ${semanticFile}`);
      return;
    }

    const resolved = resolveTokens(semantics, primitives);
    const normalized = normalizeColors(resolved, `semantics.${semanticFile}`);

    if (themeType === "light") lightSemantics = normalized;
    if (themeType === "dark") darkSemantics = normalized;

    const uiColors = replaceVariables(workbenchRaw, normalized, `workbench`);
    const semanticColors = replaceVariables(semanticRaw, normalized, `semantic`);
    const tokenColors = replaceVariables(tokenColorsRaw, normalized, `tokenColors`);

    const type = themeType.includes("light") ? "light" : "dark";
    const displaySuffix = themeType === "dark" ? "Dark" : "Light";

    const theme = {
      name: `${themeInfo.displayName} ${displaySuffix}`,
      type: type,
      colors: uiColors,
      tokenColors: tokenColors,
      semanticTokenColors: semanticColors,
    };

    if (!fs.existsSync(PATHS.outputDir)) {
      fs.mkdirSync(PATHS.outputDir, { recursive: true });
    }

    fs.writeFileSync(outputFile, JSON.stringify(theme, null, 2));
    console.log(`   ✅ Built: ${outputFile}`);

    if (normalized.bg && normalized.text) {
      checkContrast(normalized.text, normalized.bg, "text", themeType);
    }
    if (normalized.bg && normalized.textDim) {
      checkContrast(normalized.textDim, normalized.bg, "textDim", themeType);
    }
    if (normalized.bg && normalized.textMuted) {
      checkContrast(normalized.textMuted, normalized.bg, "textMuted", themeType);
    }
  });

  if (lightSemantics && darkSemantics) {
    generateColorCss(lightSemantics, darkSemantics);
    generateDesignSystemDoc(primitives, lightSemantics, darkSemantics);
  }

  console.log("\n🎉 All themes built successfully!");
}

main();

⚙️ Step 5: Configure package.json

{
  "name": "moongate-theme",
  "version": "2.2.0",
  "scripts": {
    "build": "node scripts/build.js",
    "watch": "nodemon --watch src -e yaml --exec \"pnpm run build\"",
    "prepublishOnly": "pnpm run build"
  },
  "devDependencies": {
    "js-yaml": "^4.1.1",
    "nodemon": "^3.1.14",
    "wcag-contrast": "^3.0.0"
  }
}

⚠️ Note: Make sure to run pnpm install or npm install to install all dependencies, otherwise the script will fail because wcag-contrast is missing.

🚀 Step 6: Run the Build

pnpm run build

A successful build will produce output similar to:

🚀 Building theme (DTCG standard + industrial quality checks)...

📦 Loading primitives...
📦 Loading layout tokens...
✅ Layout tokens generated: themes/moongate-layout.css
📦 Loading shared rules...
📚 Loading language rules...
   ✅ Loaded: base.yaml
   ...
✨ Loading special rules...
   ✅ Loaded: better-comments.yaml

🎨 Scanning semantic files...

🔨 Building themes...
   ✅ Built: themes/moongate-dark.json
✅ dark · text: 14.48:1
✅ dark · textDim: 12.02:1
✅ dark · textMuted: 6.96:1
   ✅ Built: themes/moongate-light.json
✅ light · text: 17.08:1
✅ light · textDim: 7.25:1
✅ light · textMuted: 7.25:1
✅ Color tokens generated: themes/moongate-colors.css
✅ Design system documentation generated: docs/DESIGN_SYSTEM.md

🎉 All themes built successfully!

Generated files:

themes/moongate-dark.json, themes/moongate-light.json – VS Code themes
themes/moongate-colors.css – Color tokens (light/dark)
themes/moongate-layout.css – Layout tokens (spacing, typography, breakpoints, etc.)
docs/DESIGN_SYSTEM.md – Complete design system documentation with variable selection protocol

📊 Step 7: Using the Generated Assets

CSS Variable Naming Rules

Generated CSS variables use the --ui- prefix, converting camelCase semantic variable names to kebab‑case. For example:

Semantic Variable	Generated CSS Variable	Description
`bg`	`--ui-bg`	Editor background
`surfaceRaised`	`--ui-surface-raised`	Raised surface background
`textMuted`	`--ui-text-muted`	Muted text color
`spacing.md`	`--ui-spacing-md`	Medium spacing

Using CSS Variables in a Blog

<link rel="stylesheet" href="/themes/moongate-colors.css">
<link rel="stylesheet" href="/themes/moongate-layout.css">

body {
  background: var(--ui-bg);
  color: var(--ui-text);
  font-family: var(--ui-typography-family-sans);
  font-size: var(--ui-typography-size-body);
}

.card {
  background: var(--ui-surface-raised);
  border: var(--ui-shadow-border) var(--ui-border);
  padding: var(--ui-spacing-md);
  border-radius: var(--ui-radius-none);
}

.button-primary:hover {
  /* State composition: base + overlay */
  background-image: linear-gradient(var(--ui-action-hover), var(--ui-action-hover));
  background-color: var(--ui-primary);
}

@media (min-width: var(--ui-breakpoint-tablet)) {
  .container {
    padding: var(--ui-spacing-lg);
  }
}

Switching Between Light and Dark Modes

Add or remove the .dark class on the root element:

document.documentElement.classList.toggle('dark');

📝 Summary

With this part, you have fully implemented an industrial‑grade build script:

✅ DTCG three‑layer architecture (primitives, semantics, components)
✅ Color normalization and circular reference detection
✅ WCAG contrast checking
✅ Automatic generation of CSS variables for colors
✅ Automatic generation of CSS variables for layout (spacing, typography, breakpoints, etc.)
✅ Automatic generation of design system documentation (including variable selection protocol)

This script not only serves the Moongate theme but can also be the engineering foundation for all your future design system projects. You now have a complete design system – from design philosophy to engineering code to cross‑platform assets.

Explore endlessly, code without limits.

⬆ Back to top

This article is part of the **VS Code Theme Development Guide* series. The original Chinese version is available on my blog: moongate.top.*

Moongate example:

3.1 Documentation system

README: bilingual, with preview images, design philosophy, a highlight list, and recommended configuration.
CHANGELOG: records changes by version, collapsing old versions and highlighting the current ones.
Visual contract: a standalone document shipped with the theme.
Design-system docs: the auto-generated DESIGN_SYSTEM.md, containing the full palette, the elevation system, WCAG contrast data, and the "variable selection protocol" — every color must follow the "primitives → semantics → components" chain; any cross-layer direct reference is architecture pollution.

3.2 Community interaction

Open source on GitHub: public source code, accepting PRs.
Feedback channel: encourage users to share calibration experiences to keep improving the visual contract.

3.3 Ecosystem integration

Better Comments preset: the official colors are built into the theme, zero-config and ready to use (the dual-source elimination mechanism is covered in the build system article).
Terminal ANSI sync: the 16-color ANSI palette maps to the theme's semantic colors, eliminating the visual split between the editor and the terminal.
Cross-platform token assets: automatically exported as CSS / SCSS / TypeScript tokens (generation is covered in the build system article), available for blogs, docs sites, and UI component libraries to reference directly — one color system running through every product.

3.4 From a Work to a Brand

Moongate is no longer just a theme. It is:

A design philosophy (cool base, semantic layering, gravity compensation, elevation system)
A visual contract (monitor calibration guide)
An extensible brand (dark/light dual stars, more variants to come)

Part 4: Summary and Outlook

At this point, the five-part series is complete. Looking back at the journey:

VS Code Theme: you started from handwritten JSON, created and published your first VS Code theme, and mastered the core mechanics and publishing flow.
Theme Engineering: through YAML modularization + a build script, you made the theme maintainable and automatically buildable.
Design System: you used the DTCG three-layer architecture to manage colors, building dark/light variants with gravity compensation.
Build System: you built a testable, verifiable build-script architecture that automates quality assurance.
Brand Ecosystem: you elevated the theme into a design system, building a complete brand ecosystem with design philosophy, a visual contract, and cross-platform assets.

v2.6.0 is the practical result of this system — every color passes industrial-grade validation, layout tokens are exported as CSS variables, design docs are auto-generated, and cross-platform tokens are produced in both SCSS and TypeScript formats.

The Moongate theme is the embodiment of these ideas. If you would like to experience this design philosophy yourself, search for Moongate Theme in the VS Code marketplace, or explore it through the links below:

If you create your own theme following this series, or have any questions or ideas, feel free to share them in the comments. The code world is vast — may your theme be seen by those who love the same moonlight.

💡 Also, if after reading this series you would like a ready-to-fork engineering template — whether to quickly swap the palette into your own theme, or to use a clean reference implementation of the system — let us know your preference in the comments. It will help us decide whether, and in what form, to provide a starter template.

Version and Maintenance Strategy

This series describes the actual state of Moongate v2.6.0. To set fair expectations about freshness, here is the series' maintenance strategy:

Version locking

All color values, scopes, and script examples in this series are based on Moongate v2.6.0. If you install a different version of the theme, some details (such as elevation colors and language rules) may differ from this article.
The "corresponds to Moongate v2.6.0" note in each article is the version-locking marker.

Update cadence

Major version updates (such as v3.0 introducing new architectural changes): the series articles will be revised in sync, so readers always learn the current best practices.
Minor version updates (such as new language support or subtle palette tweaks): the article bodies are not rewritten per release; these are recorded in the project's CHANGELOG.md. Readers can track these incremental changes via the changelog.

Compatibility considerations

VS Code version: the engines field in package.json (currently ^1.130.0) determines the range of UI keys available in workbench.yaml. If VS Code later adds many new UI keys, the theme engineering may need to extend accordingly — this is exactly what an engineering system is for.
DTCG standard: the DTCG spec is still evolving. Moongate's strategy is to keep the "primitives → semantics → components" three-layer architecture stable while embracing spec changes within each layer.

How readers can follow along

Follow the GitHub repository's CHANGELOG to track version evolution.
If you remake your own theme engineering following this series and find anything that does not match the article, we would welcome your feedback in the comments — it helps us keep the docs in sync with the code.

DEV Community: yuelinghuashu

LLM Narrative Engines, Part 6: Runtime Loop and Branching

I. A Narrative Engine's Fifth Problem: How Do You Bring Rules to Life?

II. Novel-Grade Terminal Output: Full-Width Indentation and Streaming Interception

III. Five-Layer Sandwich Prompt: Welding Constraints at Both Ends

3.1 Deterministic Rendering: Sorting Guarantees Cache Hits

3.2 Anti-Soliloquy Constraint

IV. Mother-Child Save Mechanism

V. Memory Extraction: Synchronous Weaving After Streaming

VI. The Complete Loop

VII. Costs and Limitations

VIII. Summary

Quick Reference: Complete Flow

LLM Narrative Engines, Part 5: Integration Testing and Behavior Freezing

I. A Narrative Engine's Fourth Problem: How Do You Keep Behavior Stable?

II. Golden File Testing: Freezing Parse Results

III. Parse-Time Validation

IV. Sliding-Window Aging Tests: Correct History Truncation

V. Error Scenario Testing: Ensuring Precise Error Messages

VI. The Cost

VII. Summary

LLM Narrative Engines, Part 4: Parsing Rules and Interpolation

I. A Narrative Engine's Third Problem: How Do You Parse Condition-Action Rules?

II. Rule Parsing: Splitting Conditions and Actions

2.1 Rule Name Extraction

2.2 Splitting Condition and Action

2.3 Mutex Groups

2.4 Quote Handling

III. Interpolation Syntax: Recognizing and Replacing {variable}

3.1 Why Only {角色名}?

3.2 Substitution Timing: Three Scenarios

IV. The Intersection: When Rules Meet Interpolation

Dice Expression Error Tolerance

V. Summary: The Parsing Layer Is Complete

LLM Narrative Engines, Part 3: Block Scanner and Line Numbers

I. A Narrative Engine's Second Problem: How Do Rules Become Structure?

II. See the Problem First: What Happens Without Line Numbers

III. Two-Phase Design

IV. Block Scanner: A Simple State Machine

V. Parser: Routing to Different Parse Functions

VI. Error Message Comparison

VII. The Cost

VIII. Summary

LLM Narrative Engines, Part 2: Quick Start — Write Your First Contract

I. What You'll Need

II. Clone and Build

III. Write Your First Contract

3.1 Character Name

3.2 Anchor

3.3 State

3.4 Worldview

3.5 Character Background

3.6 Opening Scene

3.7 Rules — The Heart That Brings the Character to Life

3.8 Validate

IV. First Conversation (No LLM Mode)

V. Bring in the LLM

VI. Try Changing Something

Change a State Value

Add a Dice Rule

Run Two Turns, Then Look at the Child Save

VII. Summary

LLM Narrative Engines, Part 1: From Freeform to Constrained

I. A Narrative Engine's First Problem: How Do You Express Rules?

II. See the Destination: A Real .meph Contract

III. JSON: Friendly to Programs, Hostile to People

IV. YAML: The Mirage of Simplicity

V. Plain Text: Free but Ambiguous

VI. Three Options Compared

VII. .meph Design Principles

VIII. The Cost

IX. Summary

From Code to npm: Vue 3 Component Library Publishing Guide

I. Introduction

II. Pre-Publish Preparation

2.1 Check Build Outputs

2.2 Verify package.json Distribution Contract

2.3 Manage npm Registries with nrm

2.4 Local Integration Testing

III. Tackling Two-Factor Authentication (2FA)

III. Interpolation Syntax: Recognizing and Replacing `{variable}`

3.1 Why Only `{角色名}`?

2.2 Verify `package.json` Distribution Contract