Palettes
To restyle a Parable to a brand design system, start with the Artifacts Power: it reads the person’s brand fonts, logo and design files, and gives the recipe that puts them on the Page. A Palette is the stylesheet of one Page or Pane: plain CSS that decides how it looks. It keeps appearance separate from data and logic, so styling can be changed and reviewed on its own while every Parable still looks like the rest of the product. A Palette is its own Piece, created with its Page or Pane and deleted with it. The shared design system supplies the base look: Parable’s typography, colors, square corners, icons, and the Ivory and Obsidian themes. A Palette adds only what a Pane needs on top of that. A Palette opens as palette.css. The Pane’s React code gives its elements class names, and the Palette writes selectors for those classes using ordinary CSS and the design system’s CSS custom properties, called tokens. A new Pane’s root element carries the class parable-pane and a new Page’s root carries parable-page; the starting Palette styles both, so a rule for the whole Pane goes on that class. The renderer draws each Pane inside an element of its own with display: contents and a data-parable-pane attribute; it adds no box and is not for styling. A Pane is as tall as its content: height: 100% has no sized parent to resolve against, so give the root a min-height when it must fill an area. The renderer attaches the selected stylesheet; CSS is not a value passed into the Pane and not a field in its Perception. The CSS is an implementation of the Palette: its programKey is the Palette’s key, which read_parable_contents gives as the Page’s or Pane’s paletteKey. A save that puts CSS on the Page’s or Pane’s own key is refused, because the renderer never draws it. The CSS is saved with the Parable’s draft and versioned with it. The preview can show unsaved CSS, but a previewed draft is not a saved change. Arbitrary Tailwind class strings are not compiled, so use the shared components’ props for their variants and ordinary CSS for layout. Viewing Palette source needs view permission on the palette target of its Page’s or Pane’s Policies, and changing it needs edit permission on the palette; permission to change settings does not authorize CSS changes. A Pane’s Palette styles the Pane, the Panes drawn inside it, and every Page and Pane that declares it, directly or through other Panes; it never reaches a Pane beside it that neither declares it nor is drawn inside it, so two such Panes can use the same class name and each keeps its own rules. Styles that several Panes share belong in the Palette of the Pane whose exports they style, and the Panes that use them declare that Pane. Menus, popovers, dialogs and tooltips are drawn outside every Pane, where every Palette on the Page reaches them, so give their classes names no other Pane uses. Rules for :root, html and body reach the whole document. A child or sibling combinator from a Pane’s element to the root of a Pane drawn inside it does not match through that Pane’s element; write a descendant selector. The editing preview of unsaved code applies the same rules, so a rule reaches the same Panes before and after a save. CSS delivered to a browser cannot be kept secret by hiding the source editor. When a person needs to choose a meaningful setting, give it a value in the Pane’s Perception and a control that saves it as a Preference; a hidden CSS edit is not a configuration workflow. The element the renderer draws each Pane in also decides how the Pane stacks: a z-index inside a Pane orders things within that Pane only, and the Pane the reader points at or works in lies over the other Panes, so a tooltip, menu or sheet a Pane draws itself shows on top where it spills over a neighbour. The Pane the reader points at lies over the Pane that holds the focus, so a click in one Pane never hides the tooltip of the Pane the reader points at next. A Pane that draws an open menu itself lies over every other Pane, also the Pane the reader points at, so the menu stays on top when the pointer moves onto a neighbour. A menu is open while the control that opens it has aria-expanded=“true” and aria-haspopup, or has the combobox role: give the button of a menu a Pane draws itself both attributes. If the button also names the menu with aria-controls, the Pane lifts only while that menu is in the Pane. The shared menus, selects, popovers and comboboxes draw their popup outside every Pane, so they do not lift the Pane that opens them. A shared Command drawn in a Pane does not lift the Pane either. A disclosure, such as an accordion or a tree row, has no aria-haspopup, and an expanded one does not lift its Pane. A position, isolation or z-index a Pane sets on its own root still applies. Give Page chrome that must stay above a Pane with an open menu, such as a sticky bar, a z-index of 4 or more. A brand font that a person uploaded to the Parable’s Artifacts is named by its CSS name, with a fallback stack, as in font-family: “Acme Sans”, system-ui, sans-serif. Put the stack in a custom property on the Page’s root class and use the property in every rule. Never name the family’s display name, which people can rename (see the Artifacts Power). Charts take every color from the design system’s chart tokens, which the Pane document defines for both themes. Use var(—chart-categorical-1) through var(—chart-categorical-10), in order, for co-equal categories. Use one single-hue sequential ramp for ordered amounts: —chart-sequential-HUE-1 through -9, where HUE is blossom, coral, amber, leaf, teal, blue, or fuchsia, step 1 sits nearest the page, and —chart-multi-hue-warm-N or —chart-multi-hue-cool-N add hue change across the same nine steps. Use a diverging ramp for signed values: —chart-diverging-coral-blue-1 through -11, or amber-teal or blossom-leaf, with step 6 at zero. When one subject is read against its context, draw the context in —theme-chart-context-fill and the subject in one categorical color. Axes, grid lines, and labels use —theme-chart-axis, —theme-chart-grid, and —theme-chart-label. CHART_PALETTES and getColorByIndex from parable/panes/placeholders return the same var() references. Do not invent token names: a name the Pane document does not define, such as —parable-chart-categorical-1, resolves to nothing and every series falls back to one color. Use one palette per view and never give one hue two meanings. A literal hex or named color freezes one theme and is a defect even when it looks right; tokens repaint when the theme changes. In a Workspace where a Visible Platform Parable gives a shared stylesheet, a Palette may not write the exact value of one of its tokens, such as a color, a font size, a spacing value or the first font family: write var() of the token that Warnings & Errors name (rule shared-tokens). A save that adds such a value is refused, and Prepare and Publish are refused while one remains.- Ask Ponder to style a Pane. Ponder reads the Pane’s React code and class names first and starts from the shared controls and tokens, never a parallel design system.
- Ponder writes Pane-scoped selectors in the Palette and adds class names to the React code where they are missing.
- Preview the Pane beside the other Panes on its Page, in both themes and at narrow sizes.
- Save. In Published Versions the change goes into a Patch for review before it is published.