gridaco · softmarshmallow · Mar 23, 2026 · Mar 23, 2026 · Mar 23, 2026
diff --git a/docs/reference/index.md b/docs/reference/index.md
@@ -1,5 +1,9 @@
 ---
 id: intro
+tags:
+  - reference
+  - user-facing
+
 ---
 
 # API References & Blueprints

diff --git a/docs/reference/italic-fonts.md b/docs/reference/italic-fonts.md
@@ -1,3 +1,13 @@
+---
+title: Italic Fonts
+format: md
+tags:
+  - reference
+  - user-facing
+  - typography
+  - fonts
+---
+
 # Italic Fonts
 
 This document provides a comprehensive reference table of real-world font examples organized by italic detection scenarios. Each scenario represents a different way that font families can implement italic styles, from traditional static fonts to modern variable fonts with complex axis configurations.

diff --git a/docs/reference/italic.md b/docs/reference/italic.md
@@ -1,3 +1,13 @@
+---
+title: Italic (and Oblique Model Design)
+format: md
+tags:
+  - reference
+  - user-facing
+  - typography
+  - fonts
+---
+
 # Italic (and Oblique Model Design)
 
 This document provides an in-depth technical analysis of italic and oblique styles in digital typography, focusing on font metadata specifications, rendering engine implementations, platform-specific behaviors, design tool capabilities, multilingual considerations, and user experience design.

diff --git a/docs/reference/open-type-features.md b/docs/reference/open-type-features.md
@@ -1,3 +1,13 @@
+---
+title: OpenType Features Reference
+format: md
+tags:
+  - reference
+  - user-facing
+  - typography
+  - open-type
+---
+
 # OpenType Features Reference
 
 This document provides a comprehensive reference for OpenType features based on the [Microsoft OpenType specification](https://learn.microsoft.com/en-us/typography/opentype/spec/featurelist).

diff --git a/docs/reference/open-type-script-tags.md b/docs/reference/open-type-script-tags.md
@@ -1,3 +1,13 @@
+---
+title: OpenType Script Tags
+format: md
+tags:
+  - reference
+  - user-facing
+  - typography
+  - open-type
+---
+
 # OpenType Script Tags
 
 OpenType script tags are standardized four-letter identifiers used within the OpenType font specification to represent writing systems (scripts) such as Latin, Cyrillic, Han, Arabic, and others. These tags are embedded in font tables—specifically GSUB (Glyph Substitution) and GPOS (Glyph Positioning)—to enable advanced text layout and shaping according to the typographic and linguistic rules of each script. Script tags allow layout engines to apply the correct features and substitutions for each script encountered in text.

diff --git a/docs/reference/open-type-variable-axes.md b/docs/reference/open-type-variable-axes.md
@@ -1,3 +1,13 @@
+---
+title: Open Type Variable Axes Reference
+format: md
+tags:
+  - reference
+  - user-facing
+  - typography
+  - open-type
+---
+
 # Open Type Variable Axes Reference
 
 ## Overview

diff --git a/docs/tags.yml b/docs/tags.yml
@@ -0,0 +1,182 @@
+# Docusaurus docs tags — shared vocabulary for navigation, search, and RAG chunking.
+# Keys are referenced from doc frontmatter (`tags: [key, ...]`).
+
+internal:
+  label: Internal
+  permalink: /internal
+  description: Engineering and WG material for Grida builders (not end-user product guides).
+
+user-facing:
+  label: User-facing
+  permalink: /user-facing
+  description: Documentation intended for product users, integrators, and doc authors consuming stable references.
+
+reference:
+  label: Reference
+  permalink: /reference
+  description: Stable technical reference tables, glossaries, and specifications.
+
+wg:
+  label: WG
+  permalink: /wg
+  description: Working group notes, feature specs, and implementation plans.
+
+research:
+  label: Research
+  permalink: /research
+  description: Upstream research and deep dives (e.g. browser engine internals) informing design decisions.
+
+platform:
+  label: Platform
+  permalink: /platform
+  description: Multi-tenant platform, routing, domains, and edge operations.
+
+infra:
+  label: Infra
+  permalink: /infra
+  description: Hosting, DNS, edge configuration, and operational architecture.
+
+routing:
+  label: Routing
+  permalink: /routing
+  description: URL models, universal routes, and navigation contracts.
+
+historical:
+  label: Historical
+  permalink: /historical
+  description: Archived snapshots kept for audit trails; may not reflect current behavior.
+
+canvas:
+  label: Canvas
+  permalink: /canvas
+  description: Grida Canvas engine, 2D graphics, WASM runtime, and scene graph concerns.
+
+svg:
+  label: SVG
+  permalink: /svg
+  description: SVG import, parsing, and SVG-aligned rendering behavior.
+
+vector:
+  label: Vector
+  permalink: /vector
+  description: Paths, vector networks, curve geometry, and vector editing.
+
+rendering:
+  label: Rendering
+  permalink: /rendering
+  description: Rasterization, paints, opacity, blend modes, and draw pipelines.
+
+painting:
+  label: Painting
+  permalink: /painting
+  description: Fills, strokes, noise, patterns, and paint servers.
+
+performance:
+  label: Performance
+  permalink: /performance
+  description: Culling, caching, tiling, budgets, hashing, and throughput.
+
+testing:
+  label: Testing
+  permalink: /testing
+  description: Test methodology, suites, reftests, and QA strategy.
+
+typography:
+  label: Typography
+  permalink: /typography
+  description: Fonts, shaping, OpenType, variable axes, and text layout.
+
+text:
+  label: Text
+  permalink: /text
+  description: Rich text, attributed strings, editing model, and persistence.
+
+fonts:
+  label: Fonts
+  permalink: /fonts
+  description: Font loading, fallback, italic/oblique behavior, and font resources.
+
+open-type:
+  label: OpenType
+  permalink: /open-type
+  description: OpenType layout features, tags, and font table references.
+
+editor:
+  label: Editor
+  permalink: /editor
+  description: Editor UX, tools, selection, and authoring surfaces.
+
+authoring:
+  label: Authoring
+  permalink: /authoring
+  description: Parametric design, scaling, and author-side workflows.
+
+layout:
+  label: Layout
+  permalink: /layout
+  description: Auto-layout, constraints, and spatial composition.
+
+figma:
+  label: Figma
+  permalink: /figma
+  description: Figma interchange, Kiwi format, and import pipelines.
+
+import:
+  label: Import
+  permalink: /import
+  description: Bringing external formats into Grida (SVG, Figma, assets).
+
+format-schema:
+  label: Format & schema
+  permalink: /format-schema
+  description: .grida file format, naming, serialization, and schema evolution.
+
+resources:
+  label: Resources
+  permalink: /resources
+  description: Images, blobs, byte stores, and resource identity.
+
+wasm:
+  label: WASM
+  permalink: /wasm
+  description: WebAssembly constraints and browser-hosted engine concerns.
+
+masks:
+  label: Masks
+  permalink: /masks
+  description: Masking, clips, and matte operations.
+
+filters:
+  label: Filters
+  permalink: /filters
+  description: Image filters and visual effects.
+
+ai:
+  label: AI
+  permalink: /ai
+  description: Assistant tools, model-facing operations, and AI UX.
+
+collaboration:
+  label: Collaboration
+  permalink: /collaboration
+  description: CRDTs, identity, and multi-user consistency.
+
+css:
+  label: CSS
+  permalink: /css
+  description: CSS properties, web styling alignment, and design-to-code mapping.
+
+icu:
+  label: ICU
+  permalink: /icu
+  description: ICU, Unicode, locale-aware text, and cross-script behavior.
+
+chromium:
+  label: Chromium
+  permalink: /chromium
+  description: Chromium / Blink / cc compositor source research notes.
+
+compositing:
+  label: Compositing
+  permalink: /compositing
+  description: Layers, surfaces, tiles, and GPU composition.
diff --git a/docs/wg/feat-2d/curve-decoration.md b/docs/wg/feat-2d/curve-decoration.md
@@ -1,5 +1,12 @@
 ---
 title: Curve Decorations (2D)
+tags:
+  - internal
+  - wg
+  - canvas
+  - vector
+  - rendering
+
 ---
 
 # Curve Decorations (2D)

diff --git a/docs/wg/feat-2d/investigation-viewport-culling.md b/docs/wg/feat-2d/investigation-viewport-culling.md
@@ -2,6 +2,13 @@
 title: "Investigation: Viewport Culling & Camera Caching"
 status: rejected
 date: 2026-03-22
+tags:
+  - internal
+  - wg
+  - canvas
+  - performance
+  - rendering
+
 ---
 
 # Investigation: Viewport Culling & Camera Caching

diff --git a/docs/wg/feat-2d/optimization.md b/docs/wg/feat-2d/optimization.md
@@ -1,5 +1,12 @@
 ---
 title: Rendering Optimization Strategies
+tags:
+  - internal
+  - wg
+  - canvas
+  - performance
+  - rendering
+
 ---
 
 # Rendering Optimization Strategies

diff --git a/docs/wg/feat-2d/stroke-fill-opacity.md b/docs/wg/feat-2d/stroke-fill-opacity.md
@@ -1,5 +1,11 @@
 ---
 title: "Stroke-Fill Opacity Compositing"
+tags:
+  - internal
+  - wg
+  - canvas
+  - rendering
+
 ---
 
 # Stroke-Fill Opacity Compositing

diff --git a/docs/wg/feat-ai/tools-image.md b/docs/wg/feat-ai/tools-image.md
@@ -1,3 +1,12 @@
+---
+title: Image Tools (for AI)
+tags:
+  - internal
+  - wg
+  - ai
+  - editor
+---
+
 # Image Tools (for AI)
 
 This document proposes the philosophical basis for image manipulation tools that enable AI agents to generate, enhance, and transform visual content within the design canvas.

diff --git a/docs/wg/feat-ai/tools.md b/docs/wg/feat-ai/tools.md
@@ -1,3 +1,12 @@
+---
+title: Fundamental Tools (for AI)
+tags:
+  - internal
+  - wg
+  - ai
+  - editor
+---
+
 # Fundamental Tools (for AI)
 
 This document proposes the philosophical basis for the fundamental toolset, enabling machines to design like humans.

diff --git a/docs/wg/feat-authoring/index.md b/docs/wg/feat-authoring/index.md
@@ -1,5 +1,11 @@
 ---
 title: Authoring (WG)
+tags:
+  - internal
+  - wg
+  - editor
+  - authoring
+
 ---
 
 Authoring features are a collection of **authoring-time** behaviors in the editor: operations that **rewrite node parameters** to achieve an intended visual result, rather than relying on runtime transforms or renderer-specific tricks.

diff --git a/docs/wg/feat-authoring/parametric-scaling.md b/docs/wg/feat-authoring/parametric-scaling.md
@@ -1,5 +1,11 @@
 ---
 title: Scale tool (K) — parameter-space scaling (A.k.a Apply Scale or K-Scale)
+tags:
+  - internal
+  - wg
+  - editor
+  - authoring
+
 ---
 
 | feature id           | status   | description                                  | PRs                                               |

diff --git a/docs/wg/feat-crdt/id.md b/docs/wg/feat-crdt/id.md
@@ -1,6 +1,11 @@
 ---
 title: CRDT Object ID Model
 description: A working group draft describing the Grida ID Model (for CRDT) feature for the core engine.
+tags:
+  - internal
+  - wg
+  - collaboration
+
 ---
 
 # Grida ID Model (for CRDT)

diff --git a/docs/wg/feat-css/glossary/css_properties.json5.md b/docs/wg/feat-css/glossary/css_properties.json5.md
@@ -1,6 +1,11 @@
 ---
 title: "css_properties.json5"
 description: "Chromium Blink's single source of truth for CSS property metadata, used as a reference for browser-grade CSS cascade implementation"
+tags:
+  - internal
+  - wg
+  - css
+
 ---
 
 # About `css_properties.json5`

diff --git a/docs/wg/feat-editor/index.md b/docs/wg/feat-editor/index.md
@@ -1,5 +1,10 @@
 ---
 title: Editor Features (WG)
+tags:
+  - internal
+  - wg
+  - editor
+
 ---
 
 Editor features are a collection of **Grida editor-specific** behaviors and capabilities. These documents focus on **practical implementation details** over mathematical abstractions, emphasizing real-world UX and editor workflows.