diff --git a/packages/docs/.vitepress/sidebars.ts b/packages/docs/.vitepress/sidebars.ts
index 1b5dba920..9ae9a2854 100644
--- a/packages/docs/.vitepress/sidebars.ts
+++ b/packages/docs/.vitepress/sidebars.ts
@@ -81,6 +81,7 @@ export const referenceSidebar = (prefix: string, label: string): DefaultTheme.Si
       { text: 'CLI', link: `${prefix}/reference/cli` },
       { text: 'Node Types', link: `${prefix}/reference/node-types` },
       { text: 'Scene Graph', link: `${prefix}/reference/scene-graph` },
+      { text: 'DOM/CSS Mapping', link: `${prefix}/reference/dom-css-mapping` },
       { text: 'File Format', link: `${prefix}/reference/file-format` },
     ],
   },
diff --git a/packages/docs/reference/dom-css-mapping.md b/packages/docs/reference/dom-css-mapping.md
new file mode 100644
index 000000000..90bc4e46e
--- /dev/null
+++ b/packages/docs/reference/dom-css-mapping.md
@@ -0,0 +1,63 @@
+# DOM/CSS mapping reference
+
+OpenPencil maps browser-computed DOM/CSS styles into SceneGraph fields through `@open-pencil/dom-css`. Browser adapters should use native DOM/CSSOM and `getComputedStyle()` as the source of truth. Headless conversion is an approximation for tests and CLI usage.
+
+## Layout
+
+| CSS | SceneGraph | Notes |
+|---|---|---|
+| `display: flex` / `inline-flex` | `layoutMode` | `flex-direction: row` maps to horizontal; `column` maps to vertical. |
+| `justify-content` | `primaryAxisAlign` | Supports start, center, end/flex-end, and space-between. |
+| `align-items` | `counterAxisAlign` | Supports start, center, end/flex-end, stretch, and baseline. |
+| `align-self` | `layoutAlignSelf` | Supports start, center, end/flex-end, stretch, and baseline. |
+| `flex-wrap: wrap` | `layoutWrap: WRAP` | Counter-axis spacing is preserved when gaps are available. |
+| `gap`, `row-gap`, `column-gap` | `itemSpacing`, `counterAxisSpacing` | Axis-aware: row and column gaps swap meaning for column flex direction. |
+| `padding-*` | `paddingTop/Right/Bottom/Left` | Browser-computed physical values are preferred. |
+| `position: absolute/fixed`, `left`, `top` | `layoutPositioning`, `x`, `y` | Right/bottom constraints are not mapped yet. |
+| `overflow: hidden/clip` | `clipsContent` | Other overflow values are ignored. |
+| `width`, `height`, min/max sizes | node size constraints | Browser-computed pixel values are preferred. |
+
+## Paint, stroke, and effects
+
+| CSS | SceneGraph | Notes |
+|---|---|---|
+| `background-color` | solid fill | Transparent values are ignored. |
+| `border-color`, `border-*-color` | stroke color | First available border color is used. |
+| `border-width`, `border-*-width` | stroke weight / independent stroke weights | Side-specific widths set independent stroke weights. |
+| `border-style: dashed/dotted` | `dashPattern` | Unsupported border styles fall back to solid. |
+| `border-radius`, `border-*-radius` | corner radii | Independent corners are preserved when sides differ. |
+| `opacity` | node opacity | Numeric computed value. |
+| `box-shadow` | drop shadow | Simple shadows only; see parser audit before expanding. |
+
+## Text
+
+| CSS | SceneGraph | Notes |
+|---|---|---|
+| `color` | text fill | Uses core color parsing. |
+| `font-family` | `fontFamily` | Uses first family token. |
+| `font-size` | `fontSize` | Pixel/rem-ish numeric values. |
+| `font-weight` | `fontWeight` | Numeric values. |
+| `font-style: italic` | `italic` | Other styles ignored. |
+| `line-height` | `lineHeight` | Numeric computed values. |
+| `letter-spacing` | `letterSpacing` | Numeric computed values. |
+| `text-align` | horizontal text alignment | Supports center, right, justified; defaults left. |
+| `text-decoration-line` | underline / strikethrough | Decoration style/thickness are not mapped yet. |
+| `text-transform` | `textCase` | Uppercase, lowercase, and capitalize map to SceneGraph text case. |
+| `white-space: nowrap` | `maxLines = 1` | Other white-space values are not mapped yet. |
+| `text-shadow` | drop shadow effect | Simple shadows only. |
+
+## Browser-oracle but not mapped yet
+
+These values are collected or covered by browser oracle tests but do not yet have a stable SceneGraph mapping:
+
+- `aspect-ratio`
+- `object-fit`
+- complex gradients
+- CSS filters
+- multi-shadow lists
+- media-query-specific provenance
+- pseudo-elements
+
+## Headless limitations
+
+The headless runtime uses maintained parsers for HTML (`parse5`) and stylesheets (`@acemir/cssom`), but still has limited approximations for selector matching, shorthand expansion, inline style text, `calc()`, and simple shadows. Do not expand those with ad hoc parsers. See [`../development/dom-css-parser-audit.md`](../development/dom-css-parser-audit.md).