Docs
Pixels
Pixels are Sociallux's UI contract layer. They define how a surface is structured, laid out, styled, and adapted to its host container without tying that surface to one specific app shell.
Core concept
A pixel is a versioned display contract that lives alongside atoms, lexemes, and verbs. Where atoms hold data and verbs drive actions, pixels define presentation. They let you author a layout once in Sociallux and render it anywhere a compatible renderer exists.
Portable
A pixel is JSON, not a hard-coded component. The same contract can be rendered in different apps as long as they agree on the renderer and the contract version.
Declarative
Pixels describe structure, layout, style, and a small set of local affordances. They do not ship arbitrary code or app-specific business logic.
Container-aware
Responsive behavior is based on the size of the pixel's host container. That makes pixels useful for full pages, side panels, embedded widgets, and admin surfaces.
Themeable
A pixel can own exact visual values, or it can rely on host-provided CSS variables like `var(--primary)` and `var(--surface)` so the destination app controls branding.
Structure
Pixels have a simple layered model: a stored resource, a contract payload, a node tree, and a renderer that interprets the contract.
Resource
A stored Pixel resource has ownership, sharing, visibility, versioning, and a `data` payload containing the contract.
Contract
The current contract is `schemaVersion: 1` with a `layout.root` node that defines the rendered tree.
Node tree
Each node is one of `container`, `text`, or `button`, with optional `layout`, `style`, `responsive`, `behavior`, and `children` fields.
Renderer
The renderer turns the contract into UI using flex, grid, CSS styling, and container-query breakpoints. The contract stays platform-agnostic; the renderer is platform-specific.
{
"schemaVersion": 1,
"mount": {
"sizing": "parent"
},
"layout": {
"root": {
"id": "landing-shell",
"kind": "container",
"layout": {
"mode": "flex",
"direction": "column",
"gap": "16px"
},
"style": {
"background": "var(--background)",
"color": "var(--ink)",
"padding": "24px"
},
"responsive": {
"lg": {
"layout": {
"direction": "row",
"gap": "24px"
}
}
},
"children": [
{
"id": "sidebar",
"kind": "container",
"layout": {
"mode": "flex",
"direction": "column",
"gap": "12px",
"basis": "280px",
"shrink": 0
},
"behavior": {
"collapsible": true,
"collapseLabel": "Sections"
},
"style": {
"background": "var(--surface)",
"padding": "16px",
"borderRadius": "18px",
"borderWidth": "1px",
"borderStyle": "solid",
"borderColor": "var(--border)"
},
"children": [
{
"id": "sidebar-title",
"kind": "text",
"props": {
"text": "Pixel navigation"
},
"style": {
"fontSize": "1.125rem",
"fontWeight": 700
}
}
]
},
{
"id": "content",
"kind": "container",
"layout": {
"mode": "grid",
"columns": "1fr",
"gap": "16px",
"grow": 1
},
"responsive": {
"md": {
"layout": {
"columns": "repeat(2, minmax(0, 1fr))"
}
}
},
"children": [
{
"id": "headline",
"kind": "text",
"props": {
"text": "Pixels compose layout as data"
},
"layout": {
"gridColumn": "1 / -1"
},
"style": {
"fontSize": "1.5rem",
"fontWeight": 700
}
}
]
}
]
}
}
}What pixels can express
The current contract focuses on layout and presentation. It is rich enough to define full page shells and embedded surfaces, while still staying predictable and safe to render.
Layout
Containers can use flex or grid. Flex children can opt into grow, shrink, and basis. Grid children can place themselves with `gridColumn` and `gridRow`.
Styling
Nodes can define spacing, sizing, background, borders, typography, shadow, display, overflow, and opacity. Values are CSS-style tokens so they stay portable.
Responsiveness
Nodes can provide `sm`, `md`, and `lg` overrides for layout and style. Those overrides activate when the pixel container reaches 400px, 640px, and 900px respectively.
Local affordances
Container nodes can be collapsible with a local toggle. This is intentionally small-scope behavior that does not require app-specific integration.
How pixels are used
Pixels are useful when you want Sociallux to own the shape of a UI surface while another app, page, or product owns the surrounding shell, authentication model, and theme context.
Common fits
- Page shells with sidebars, headers, and content regions
- Reusable dashboard layouts that need to adapt between narrow and wide containers
- Embeddable admin panels or widgets inside another product
- Branded marketing or settings surfaces whose structure is centrally authored in Sociallux
Typical flow
- Author the structure in Pixel Studio using containers, text, buttons, flex/grid layout, and responsive overrides.
- Save the pixel as a versioned Sociallux resource with ownership and sharing rules.
- Fetch the pixel contract from the API in the consuming surface.
- Render it with a platform-specific renderer and wrap it in the host app's container and theme tokens.
Concept versus implementation
This page explains what pixels are and how they fit into the platform. If you need the practical implementation steps for using a Sociallux pixel in another product, use the dedicated walkthrough in the use-case library.