AI-native design editor. Open-source Figma alternative.
docs(dom-css): add mapping reference
Danila Poyarkov49fefcd3a065
diff --git a/packages/docs/.vitepress/sidebars.ts b/packages/docs/.vitepress/sidebars.tsindex 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.mdnew file mode 100644index 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).