naizo
Build and update self-persisting interactive HTML applications (dashboards, interactive studios, personal trackers, design option labs, calculators, visual canvases, engineering notebooks, plans, specs, checklists, triage boards, and custom micro-tools) using naizo.js and its built-in #naizodb JSON database. Activate whenever generating an interactive HTML application or inspecting/editing an existing HTML file that uses <script id="naizodb" type="application/json"> or naizo / data-naizo attributes.
- License 许可
- MIT
- 所属仓库
- nickosh/naizo
- 最近更新
- 2026-11-14
- Stars
- ★ 1
- Forks
- 0
01 前言 Front Matter
- name
- naizo
- license
- MIT
- description
- Build and update self-persisting interactive HTML applications (dashboards, interactive studios, personal trackers, design option labs, calculators, visual canvases, engineering notebooks, plans, specs, checklists, triage boards, and custom micro-tools) using naizo.js and its built-in #naizodb JSON database. Activate whenever generating an interactive HTML application or inspecting/editing an existing HTML file that uses <script id="naizodb" type="application/json"> or naizo / data-naizo attributes.
03 SKILL.md 正文
Naizo (naizo.js) — Self-Persisting HTML & AI Agent Co-Editing Skill
Use naizo.js (npm package naizojs) to turn any single .html file into a living, self-persisting application whose state syncs between the browser DOM, localStorage, and <script id="naizodb" type="application/json"> on disk.
In Japanese, naizō (ないぞう) means both 内蔵 (built-in / housed within) and 内臓 (internal organs): <script id="naizodb"> is the built-in JSON database inside <head>, and naizo.js provides the reactive internal organs that bind inputs, repeat lists, and sync human browser edits with AI agent disk edits.
1. Golden Rules for AI Agents (Never Violate)
<body>is the template;<script id="naizodb">is the canonical data:- When linked to a local file via the File System Access API (
⌘S/Ctrl+SorLink Disk),naizo.jssurgically rewrites only the<script id="naizodb">...</script>block on disk (D16). It does not rewrite<body>markup on disk during normal saves. - To read human edits from disk: Always parse
<script id="naizodb" type="application/json">in<head>. Never scrape<body>inputvalueorcheckedattributes to read current state. - To update data on disk: Modify the JSON inside
<script id="naizodb">(formatted with 2-space indentation and<escaped as\u003c). If the user has the file open and linked in their browser,naizo.jsdetectsfile.lastModifiedwithin ~2 seconds and merges your changes into the live page without clobberingdocument.activeElement. - To update the UI or layout: Edit the HTML/CSS inside
<body>(and add matching initial keys to#naizodbif needed).
- When linked to a local file via the File System Access API (
- Preserve pass-through keys (
D15,EC14):naizo.jsmaintains an in-memoryNaizoDatabasestore and maps each rendered[naizo-item]DOM row to its source object via aWeakMap.- Unbound keys in
fields, unbound arrays inlists, and extra properties on list item objects (such as"id","estimate","updatedAt", or custom per-card dictionary keys) pass through untouched. When editing#naizodbon disk, always preserve existing keys you did not intend to remove.
- Explicit binding only (
D08,D12,EC11,EC49):- Bind elements exclusively with
naizo="key"ordata-naizo="key". Unannotated inputs (like search bars or filter dropdowns) are never implicitly captured, andidornameattributes are never used as fallback binding keys.
- Bind elements exclusively with
- Wrap
<label>around inputs inside[naizo-item](EC39):- Never use
<label for="some-id">+<input id="some-id">inside a repeating[naizo-item], because cloned rows would share duplicate DOMidattributes. Always wrap<label>directly around the control (<label><input type="checkbox" naizo="done" /><span>Done</span></label>).
- Never use
- Scope documents with
<html naizo-id="...">(D13,EC11):- Add a descriptive
naizo-id="project-artifact-slug"on<html>(or"_meta": { "id": "..." }) solocalStoragecaches and IndexedDB file handles never collide when multiple HTML tools are opened onlocalhostorfile://.
- Add a descriptive
- Never filter
[naizo-item]rows by removing them from the DOM (D43):- Removing a
[naizo-item]node deletes its object fromdb.lists. For search or category filtering, togglerow.hidden = !matches(or CSSdisplay: none).
- Removing a
2. Core HTML Structure & #naizodb Schema
Every naizo.js HTML document embeds <script id="naizodb" type="application/json"> at the top of <head> followed by naizo.js:
<!doctype html>
<html lang="en" naizo-id="my-artifact-id">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Artifact Title</title>
<!-- 1. Canonical #naizodb JSON state (2-space indented, '<' escaped as \u003c) -->
<script id="naizodb" type="application/json">
{
"_meta": {
"id": "my-artifact-id"
},
"fields": {
"title": "Artifact Title",
"owner": "Alex",
"status": "Draft"
},
"lists": {
"tasks": [
{
"id": "task-1",
"done": false,
"task": "First action item",
"priority": "High"
}
]
},
"custom": {}
}
</script>
<!-- 2. Load naizo.js via npm CDN (jsDelivr or unpkg) or local ./dist/naizo.js -->
<script src="https://cdn.jsdelivr.net/npm/naizojs@latest/dist/naizo.js" defer></script>
</head>
<body>
<!-- 3. Declarative bindings in <body> -->
</body>
</html>
CDN & Local Script Options (D17, D34, D39)
- jsDelivr (readable):
https://cdn.jsdelivr.net/npm/naizojs@latest/dist/naizo.js - jsDelivr (minified, ~15.7 KB gzipped):
https://cdn.jsdelivr.net/npm/naizojs@latest/dist/naizo.min.js - unpkg:
https://unpkg.com/naizojs@latest/dist/naizo.js - Pinned version: replace
@latestwith a specific published version tag - Local / offline:
<script src="./dist/naizo.js" defer></script>(inside thenaizorepository examples, use../dist/naizo.js) - Experimental / in-development (
mainbranchdist/naizo.js):https://cdn.jsdelivr.net/gh/nickosh/naizo@main/dist/naizo.js(unreleased; pair with the@mainskill below)
3. Declarative HTML Attributes (naizo / data-naizo)
Both short naizo / naizo-* attributes and HTML5 data-naizo / data-naizo-* aliases are supported everywhere (D08):
| Short Attribute | HTML5 data-* Alias |
Placement | Behavior |
|---|---|---|---|
naizo="key" |
data-naizo="key" |
<input>, <textarea>, <select>, <details>, [contenteditable], leaf element, or [naizo-item] |
Binds to db.fields["key"] when standalone, or to item["key"] when inside or on a [naizo-item]. |
naizo-list="name" |
data-naizo-list="name" |
Container (<div>, <ul>, <ol>, <tbody>, <table>) |
Binds direct [naizo-item] children to db.lists["name"] and injects + Add Item below the list unless naizo-no-controls is present. |
naizo-item |
data-naizo-item |
Direct child of [naizo-list] (<div>, <li>, <tr>, etc.) |
Marks a repeating row/card; injects hover ↑ ↓ × toolbar unless naizo-no-controls is set on the list. |
naizo-template |
data-naizo-template |
Direct child <template> inside [naizo-list] |
Optional explicit blueprint for new items. If omitted, naizo.js auto-infers data-naizo-auto-template="true" from the first [naizo-item]. |
naizo-add="name" |
data-naizo-add="name" |
<button> (anywhere in document) |
Appends a new blank item to [naizo-list="name"] and focuses its first text field (EC31). |
naizo-remove |
data-naizo-remove |
<button> inside [naizo-item] |
Deletes the enclosing [naizo-item] from DOM and db.lists. |
naizo-move="up|down" |
data-naizo-move="up|down" |
<button> inside [naizo-item] |
Moves the enclosing [naizo-item] up or down in DOM and db.lists. |
naizo-no-controls |
data-naizo-no-controls |
[naizo-list] |
Suppresses auto-injected ↑ ↓ × and + Add Item buttons so you can use custom buttons or modals. |
naizo-ignore |
data-naizo-ignore |
Any element | Excludes the element and its subtree from state binding while preserving it in auto-templates and exported HTML (D12, EC07). |
naizo-strip |
data-naizo-strip |
Any element | Excludes the element and its subtree from state binding and strips it from auto-templates and exportHTML() / downloadHTML() (D12, D47). |
naizo-id="scope" |
data-naizo-id="scope" |
<html> or <body> |
Scopes localStorage and IndexedDB keys (<path>::<scope>) to avoid collisions on localhost. |
naizo-mode="online|local|auto" |
data-naizo-mode="online|local|auto" |
<html> or <body> |
Overrides automatic Local Mode vs. Online Mode detection (D41, EC48). |
naizo-manual |
data-naizo-manual |
<html>, <body>, or <script> |
Disables automatic initNaizo() boot when loading the browser IIFE bundle. |
naizo-get="url" |
data-naizo-get="url" |
<button>, <a>, or any element |
Fetches JSON or text via GET and routes 2xx responses via naizo-into (or hydrates #naizodb when naizo-into is omitted, D43, D51). |
naizo-post="url" |
data-naizo-post="url" |
<button> or any element |
Flushes pending edits and sends a CORS-safelisted text/plain;charset=UTF-8 JSON POST (fire-and-forget unless naizo-into is set, D51). |
naizo-into="target" |
data-naizo-into="target" |
Element with naizo-get / naizo-post |
Routes response into field:<key>, list:<name> (Naizo.setList), custom:<key>, db, or DOM-only #selector (textContent, D22). |
naizo-path="a.b.0" |
data-naizo-path="a.b.0" |
Element with naizo-get / naizo-post |
Extracts a nested property or array index from parsed JSON using Object.hasOwn() at each step (EC24, EC50). |
naizo-body="source" |
data-naizo-body="source" |
Element with naizo-post |
Selects outgoing POST payload: db (default), fields, custom, list:<name>, or field:<key>. |
naizo-trigger="click|init|load" |
data-naizo-trigger="click|init|load" |
Element with naizo-get / naizo-post |
Fires on click (default), init (boot only when target is empty), or load (every boot). |
naizo-cors="no-cors" |
data-naizo-cors="no-cors" |
Element with naizo-post |
Sends an opaque fire-and-forget webhook POST when naizo-into is omitted (D43). |
Scalar Element Coercion & Safety Rules (D14, D22, EC12, EC15, EC18, EC21, EC25)
- Text inputs &
<textarea>:string(.value), preserving stored numbers/booleans when the string representation is unchanged (EC25). <input type="number">&<input type="range">: finitenumberornullwhen empty (EC12).<input type="checkbox">:boolean(.checked), coercing"false","0","","no", and"off"tofalse(EC25).<input type="radio">:stringvalue of the checked radio; inside[naizo-item], radionameattributes are automatically scoped per row and restored on export (EC13).<select>&<select multiple>:stringorstring[]. If#naizodbcontains a value with no matching<option>yet,naizo.jslogs a warning and preserves the stored value in memory instead of overwriting it with""(EC15).<details naizo="key">:boolean(openstate via capture-phasetogglelistener,EC12).[contenteditable]("","true","plaintext-only"): plain text viatextContent(D22,EC18— neverinnerHTML).- Self-bound
[naizo-item]:<li naizo-item contenteditable="true" naizo="text">binds the item root directly while isolatingtextContentfrom injected.naizo-item-toolsand[naizo-ignore]/[naizo-strip]children (D47,EC46). - Tables (
<tbody naizo-list>/<tr naizo-item>):.naizo-item-toolsis placed inside the last<td>/<th>of each row and.naizo-list-footeris placed immediately after<table>(EC13). - Skipped inputs (
EC21):password,file,button,submit,reset, andimageare always skipped.
4. Programmatic API (window.Naizo / window.NaizoDB) & Events
// 1. Custom JSON State (db.custom)
const activeId = Naizo.get('activeNoteId'); // Omit key to get full NaizoDatabase
Naizo.set('activeNoteId', 'note-102'); // Validates finite JSON value (EC35)
Naizo.delete('obsoleteKey');
// 2. Standalone Fields (db.fields)
const status = Naizo.getField('status');
Naizo.setField('status', 'Approved'); // Updates db.fields.status + all bound [naizo="status"] DOM nodes
Naizo.deleteField('legacyField'); // Deletes key + clears bound DOM inputs
// 3. Lists (db.lists)
const items = Naizo.getList('tasks');
Naizo.setList('tasks', [{ id: 't-1', done: false, task: 'Synced from API', priority: 'High' }]); // Replaces or clears ([] ) list safely (M8.1)
Naizo.addItem('tasks', { id: 't-2', done: false, task: 'New task', priority: 'Med' });
Naizo.updateItem('tasks', 0, { done: true }); // Shallow-merges into item 0, preserving extra keys
Naizo.moveItem('tasks', 2, 0);
Naizo.removeItem('tasks', 1);
// 4. Mini-API Client, Dynamic Subtrees, Persistence, Reset, & Export
const apiRes = await Naizo.fetch('https://api.example.com/tasks', {
method: 'GET', // 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE'
path: 'data.items',
into: 'list:tasks', // 'field:<key>' | 'list:<name>' | 'custom:<key>' | 'db' | '#selector'
}); // Resolves { url, method, ok, status, target, data, error } without throwing
Naizo.bind(containerEl); // Hydrate dynamically inserted DOM from store
const ok = await Naizo.save(); // Flush cache + await single-flight disk write (Promise<boolean>)
Naizo.reset(); // Back up dirty state to ↺ Restore and reset to initial boot baseline
await Naizo.unlink(); // Forget linked FileSystemFileHandle
const json = await Naizo.copyJSON(); // Copy 2-space #naizodb JSON to clipboard
const html = Naizo.exportHTML(); // Clean HTML snapshot with baked attributes & stripped runtime UI
const dlHtml = Naizo.downloadHTML('app.html'); // Download portable HTML with dist/naizo.min.js CDN URL
// 5. Window Lifecycle & Mutation Events
window.addEventListener('naizo:hydrate', (e) => {
// Fired on boot, external disk merge, cross-tab storage sync, full-DB fetch, ↺ Restore, and ↺ Reset
console.log('Hydrated store:', e.detail);
});
window.addEventListener('naizo:change', (e) => {
// e.detail: { scope: 'fields' | 'lists' | 'custom' | 'db' | 'reset' | 'restore', action?, list?, key?, index?, value?, db }
console.log('Changed:', e.detail);
});
window.addEventListener('naizo:item', (e) => {
// e.detail: { list, item, data, index }
console.log('New list row:', e.detail);
});
window.addEventListener('naizo:fetch', (e) => {
// e.detail: { url, method, ok, status, target, data, error }
console.log('API result:', e.detail);
});
5. Canonical Application Blueprints
Choose the blueprint that best matches the user's request (full templates live in examples/starter.html, examples/checklist.html, examples/notes.html, examples/inventory.html, and examples/weather.html in the naizo repository):
Blueprint A: Project Spec & Milestones (starter.html) / Release Checklist (checklist.html)
Use for implementation plans, PR review checklists, bug triage sheets, and release sign-offs. Needs zero custom JavaScript:
<h1 contenteditable="true" naizo="checklist_title">Pre-Release Verification Checklist</h1>
<section class="card">
<div class="meta-row">
<label>
Reviewer
<input type="text" naizo="reviewer" value="Jordan" />
</label>
<label>
Target Environment
<select naizo="environment">
<option value="Local">Local</option>
<option value="Staging" selected>Staging</option>
<option value="Production">Production</option>
</select>
</label>
<label class="ready-toggle">
<input type="checkbox" naizo="ready_for_release" />
<span>Ready for Release</span>
</label>
</div>
</section>
<section class="card">
<h2>Verification Items</h2>
<div naizo-list="checks">
<div class="check-row" naizo-item>
<label>
<input type="checkbox" naizo="done" />
<span class="sr-only">Done</span>
</label>
<label>
<span class="sr-only">Verification item</span>
<input type="text" naizo="task" placeholder="Add verification step..." />
</label>
<label>
<span class="sr-only">Priority</span>
<select naizo="priority">
<option value="High">High</option>
<option value="Med">Med</option>
<option value="Low">Low</option>
</select>
</label>
</div>
</div>
</section>
Blueprint B: Zero-DOM-Wipe Master–Detail Workspace (notes.html, D40)
Use for multi-note engineering notebooks, ADR explorers, prompt libraries, or multi-document editors with a sidebar list and active editor pane.
- Key architectural rule: Never wipe and copy note text into a single shared
<textarea>. Instead, render every note as a live[naizo-item]inside<div naizo-list="notes" naizo-no-controls>, store the selected ID indb.custom.activeNoteId, and toggle.is-active(display: flexvs.display: none) on the matching[naizo-item]pane via CSS:
<style>
[naizo-list='notes'] > .note-pane {
display: none;
}
[naizo-list='notes'] > .note-pane.is-active {
display: flex;
flex-direction: column;
}
</style>
<!-- Sidebar index (persisted category filter; ephemeral search and rendered list excluded via naizo-ignore) -->
<aside>
<input id="note-search" type="search" naizo-ignore placeholder="Search notes..." />
<select id="category-filter" naizo="category_filter">
<option value="all" selected>All Categories</option>
<option value="Architecture">Architecture</option>
<option value="Runbook">Runbook</option>
</select>
<button id="new-note-btn" type="button" naizo-ignore>+ New Note</button>
<div id="note-sidebar-list" naizo-ignore></div>
</aside>
<!-- Declarative [naizo-list] where each [naizo-item] is a full editor pane -->
<main naizo-list="notes" naizo-no-controls>
<article class="note-pane" naizo-item>
<label><input type="text" naizo="title" placeholder="Note title..." /></label>
<label>
<select naizo="category">
<option value="Architecture">Architecture</option>
<option value="Runbook">Runbook</option>
</select>
</label>
<label><input type="checkbox" naizo="pinned" /> Pinned</label>
<label><textarea naizo="body" rows="12"></textarea></label>
</article>
</main>
<script>
let syncing = false;
function syncNotebookUi() {
if (syncing) return;
syncing = true;
try {
const notes = Naizo.getList('notes');
const activeId = Naizo.get('activeNoteId') || notes[0]?.id;
const panes = document.querySelectorAll('[naizo-list="notes"] > [naizo-item]');
panes.forEach((pane, idx) => {
pane.classList.toggle('is-active', notes[idx]?.id === activeId);
});
// Render clickable sidebar items into #note-sidebar-list that call Naizo.set('activeNoteId', note.id)
} finally {
syncing = false;
}
}
document.getElementById('new-note-btn').addEventListener('click', () => {
const id = 'note-' + Date.now();
Naizo.addItem('notes', {
id,
title: 'Untitled',
category: 'Architecture',
pinned: false,
updatedAt: new Date().toISOString(),
body: '',
});
Naizo.set('activeNoteId', id);
});
window.addEventListener('naizo:hydrate', syncNotebookUi);
window.addEventListener('naizo:change', syncNotebookUi);
</script>
Blueprint C: Filterable Card Grid with Per-Item Custom Keys (inventory.html, D15)
Use for asset trackers, issue boards, or component catalogs where cards have standard bound fields plus arbitrary custom key-value properties:
- Bind standard card fields (
sku,name,status,location,qty,unitCost,notes) inside<div naizo-list="inventory" naizo-no-controls>. - Store arbitrary custom metadata keys directly on each item object in
db.lists.inventory[i](assigning keys viaObject.defineProperty/Naizo.updateItem('inventory', index, partial)so even keys like__proto__are safe,EC38). - Render a
[naizo-ignore]badge container inside each[naizo-item]card to display and edit those pass-through keys. - Use CSS Grid
cardEl.style.order = String(rank)for non-destructive sorting without mutating array indices.
Blueprint D: Lightweight Vanilla Search/Filter & Persisted Tabs (D43)
Non-destructive list search (row.hidden):
function applyFilter() {
const q = document.getElementById('search-input').value.trim().toLowerCase();
const rows = document.querySelectorAll('[naizo-list="tasks"] > [naizo-item]');
const items = Naizo.getList('tasks');
rows.forEach((row, i) => {
const text = JSON.stringify(items[i] ?? {}).toLowerCase();
row.hidden = q !== '' && !text.includes(q);
});
}
document.getElementById('search-input').addEventListener('input', applyFilter);
window.addEventListener('naizo:hydrate', applyFilter);
window.addEventListener('naizo:change', applyFilter);
Persisted collapsible sections & tabs:
- For collapsible sections, bind
<details naizo="section_open" open>directly (zero JS required). - For view tabs, bind radio buttons
<input type="radio" name="tab" value="overview" naizo="active_tab" checked>and togglepanel.hidden = panel.dataset.tab !== (Naizo.getField('active_tab') || 'overview')onnaizo:hydrateandnaizo:change.
Blueprint E: Interactive Option Lab & Human Review Prototype (D45)
When helping a user compare design directions, layout options, architecture trade-offs, or copy variants, generate a self-persisting naizo.js comparison page (design-lab.html):
- Bind option controls (
<input type="radio" name="direction" value="washi" naizo="direction">,<select naizo="measure">,<select naizo="inspector_layout">) and a review notes<textarea naizo="design_notes" rows="4">to#naizodb. - Listen to
naizo:hydrateandnaizo:changeto switch live preview styles or layout attributes (document.documentElement.dataset.direction = Naizo.getField('direction')) in real time. - Ask the user to explore the options in their browser, write feedback in the notes box, and press
⌘S/Ctrl+Sto save to disk. On the next turn, read<script id="naizodb" type="application/json">directly from disk to apply their exact selected options and written notes.
Blueprint F: Declarative Mini-API Client, Webhooks, & #net Network Rules (naizo-get / naizo-post, D43, D50, D51, D52)
Use naizo-get, naizo-post, or Naizo.fetch() when an HTML app needs to seed or sync #naizodb from public JSON APIs, static .json files, or a localhost agent server, or push #naizodb payloads to webhooks:
<!-- Seed a list once on first boot only when empty (never overwrites user edits on F5 reload) -->
<div
naizo-get="https://api.github.com/repos/nickosh/naizo/issues"
naizo-into="list:issues"
naizo-trigger="init"
></div>
<!-- Pull a nested JSON scalar into db.fields on click -->
<button
type="button"
naizo-get="https://api.example.com/status.json"
naizo-path="release.latestTag"
naizo-into="field:release_tag"
>
Sync Tag
</button>
<!-- Push db.fields to a webhook via CORS-safelisted text/plain;charset=UTF-8 POST -->
<button type="button" naizo-post="https://hooks.example.com/notify" naizo-body="fields">
Send Update
</button>
- Store-first vs. DOM-only vs. raw fetch targets (
D15,D22,D51,D52): Usenaizo-into="field:<key>",list:<name>,custom:<key>, ordb(also the default whennaizo-intois omitted on declarativenaizo-get) to persist into#naizodb.naizo-into="#selector"writes strictly viatextContent(neverinnerHTML) as a transient DOM preview without mutating#naizodb. Omittingnaizo-intoon declarativenaizo-postor omittingoptions.intoon programmaticawait Naizo.fetch(url)(any HTTP method) is non-mutating—returning{ ok, status, data }so custom JS can transform external API JSON before callingNaizo.setList()/Naizo.setField(). - Rightmost
#netwired-globe indicator & debugging (D50,EC36): Automatically appears at the right end of the status pill (API idle,API activeL→Rwave held>= 600 ms, orAPI request failedred pulse with click-to-clear) while keeping#dotand#statusexclusively for storage durability (seeexamples/weather.htmlfor a complete map + forecast + webhook blueprint).naizo.jsintentionally omits a built-in network inspector so the runtime stays light and flexible—inspect failed requests in the browser's DevToolsNetworktab. - Local Mode vs. Online Mode network rules (
D43):- Local Mode (
file://orhttp://localhost): Fetched state persists intolocalStorageand surgically into<script id="naizodb">on disk when linked so CLI AI agents immediately see remote data. Note thatfile://sendsOrigin: null(requiringAccess-Control-Allow-Origin: *to read responses, ornaizo-cors="no-cors"withoutnaizo-intofor blindPOSTwebhooks) and blocks relativefetch('./data.json')unless served viahttp://localhost. - Online Mode (
https://static hosts): Relativenaizo-get="./preset.json"works out of the box and bakes fetched data into⬇ Save to PCdownloads; browsers block mixed-contenthttp://onhttps://pages and requireAccess-Control-Allow-Private-Network: trueforlocalhostloopback calls.
- Local Mode (
6. Human-First Typography & Minimalist Design (D45 — Fallback When Author Has No Style Preference)
- Always follow the author's explicit preferences first:
- If the user or project specifies a visual style, layout structure, color palette, component library, or CSS framework (e.g., Tailwind, brutalist, dense dashboard grid, neon dark theme, or existing brand tokens), honor the author's direction completely. Never override explicit user preferences with a default house style.
- Default fallback when the author has NOT specified styling preferences (
Washi Editorialminimalism):- When the user asks for an HTML tool, doc, plan, or app without specifying visual styling, avoid stereotypical AI "neuro-slop" (nested multi-column bento cards, heavy drop shadows, neon gradients, uppercase pill-badge clutter on every heading, and cramped multi-pane sidebars).
- Default to a calm, human-readable editorial layout:
- Palette: Warm paper background in light mode (
#faf8f5surface,#ffffffelevated inputs,#1c1b18ink,#57534emuted prose,#e5e0d8hair-thin1pxborders,#a8432bterracotta accent) and warm charcoal in dark mode (#141311surface,#1c1b18elevated inputs,#ece8e1ink,#a6a096muted prose,#2e2c28borders,#e07a5faccent). - Typography & Measure: Pair an editorial serif (
'Newsreader','Iowan Old Style',Georgia,serif) for headings with a clean humanist sans-serif ('Plus Jakarta Sans',system-ui,sans-serif) for body copy (16px–16.5px,line-height: 1.65–1.75) inside a calm single-column container (max-width: 760px–900px), separating sections with hair-thin1pxhorizontal rules instead of nested boxes. - Punctuation & Tables: Prefer spaced en-dashes (
–) over unspaced em-dashes in prose. Keep reference tables to at most 3 balanced columns (grouping secondary metadata as compact block badges inside the first cell) and never setwhite-space: nowrapon columns containing long attribute or method signatures.
- Palette: Warm paper background in light mode (
- Theme persistence without dirtying initial boot state (
"theme": "system",EC48,D45):- When adding a persistent Light/Dark theme toggle (
naizo="theme"), initialize"theme": "system"in#naizodband let CSS@media (prefers-color-scheme: dark) { html:not([data-theme='light']) { ... } }handle OS dark-mode detection automatically. - Never call
Naizo.setField('theme', 'dark')on initial page load based onwindow.matchMedia, because mutatingstoreon boot marks the document dirty againstinitialDiskDband prematurely surfaces the Online Mode↺ Resetbutton before the user has made any edits. CallNaizo.setField('theme', nextTheme)only when the user explicitly clicks the theme toggle.
- When adding a persistent Light/Dark theme toggle (
7. Surgical Disk Editing Protocol for CLI / IDE AI Agents
When modifying an existing naizo.js .html file on disk to update data (fields, lists, or custom):
- Read the file and extract the JSON inside
<script id="naizodb" type="application/json">...</script>. - Parse the JSON and update
db.fields,db.lists, ordb.customwhile keeping untouched keys intact. - Update
db._meta = { ...db._meta, updatedAt: new Date().toISOString() }. - Serialize with
JSON.stringify(db, null, 2).replace(/</g, '\\u003c')and replace only the<script id="naizodb">...</script>block in the HTML file (using a callback replacement function so$1or$&inside user JSON values are never interpreted as regex capture groups):
node -e '
const fs = require("fs");
const file = "plan.html";
const html = fs.readFileSync(file, "utf8");
const re = /(<script\b[^>]*\bid\s*=\s*(?:"naizodb"|\x27naizodb\x27|naizodb(?=[>\s/]))[^>]*>)([\s\S]*?)(<\/script>)/i;
const match = html.match(re);
if (!match) throw new Error("Missing #naizodb block");
const db = JSON.parse(match[2]);
// Mutate db.fields, db.lists, or db.custom here:
db.fields.status = "Approved";
db._meta = { ...db._meta, updatedAt: new Date().toISOString() };
const json = JSON.stringify(db, null, 2).replace(/</g, "\\u003c");
fs.writeFileSync(file, html.replace(re, (_m, open, _inner, close) => `${open}\n${json}\n${close}`), "utf8");
'
8. Installing This Skill in Your Workspace
To equip Claude Code, Antigravity, Cursor, GitHub Copilot, Gemini CLI, or Codex with this skill in any repository, install it via the GitHub CLI (gh skill), the npm Skills CLI (npx skills), or curl:
# 1. GitHub CLI (gh v2.90+ — installs from the latest published release)
gh skill install nickosh/naizo naizo
# 2. npm Skills CLI (npx skills)
npx skills add nickosh/naizo --skill naizo
# 3. Direct curl / file copy (no CLI required)
mkdir -p .agents/skills/naizo && curl -fsSL https://naizo.js.org/SKILL.md -o .agents/skills/naizo/SKILL.md
mkdir -p .claude/skills/naizo && curl -fsSL https://naizo.js.org/SKILL.md -o .claude/skills/naizo/SKILL.md
Experimental / In-Development (main Branch)
To preview unreleased features from main before the next tagged release is published, pair the in-development dist/naizo.js bundle with the @main skill (note: main is under active development and may contain experimental or not-yet-released changes):
<!-- In-development runtime directly from main (or local ./dist/naizo.js) -->
<script src="https://cdn.jsdelivr.net/gh/nickosh/naizo@main/dist/naizo.js" defer></script>
# In-development AI skill from main
gh skill install nickosh/naizo naizo@main
npx skills add nickosh/naizo@main --skill naizo
mkdir -p .agents/skills/naizo && curl -fsSL https://raw.githubusercontent.com/nickosh/naizo/main/skills/naizo/SKILL.md -o .agents/skills/naizo/SKILL.md
04 同仓库更多 Skills
site
暂无简介
naizo-closeout
Close naizo development sessions, useful development slices, and milestones by reconciling implementation evidence with the project memory documents. Use when wrapping up or handing off work, ending a state-changing session, finishing a PLAN task or milestone, or updating project memory after implementation. Do not use for read-only exploration that produced no durable decision, blocker, reproduced edge case, or repository change.