# Gessi Plain Reference
Gessi is a dependency-free CSS and native Web Component library for expressive HTML, retro interfaces, browser desktops, media effects, and Markdown content.
Use this page when you want the docs without the visual interface. It is also the best source to give an AI coding agent.
## First Project
1. Choose the CDN snippet for a plain HTML page, or the package imports for an existing app.
2. Start with ordinary semantic HTML. Add a Gessi component when you need reusable chrome or interaction.
3. Use a theme only around the part of the page that should adopt it.
4. Use the full docs for examples and the component playground.
## Install
Plain HTML:
```html
```
Bundlers and SSR:
```js
import "@pol-cova/gessi/css";
import "@pol-cova/gessi/components";
```
## Entry Points
- `@pol-cova/gessi`: package default stylesheet.
- `@pol-cova/gessi/css`: stylesheet only.
- `@pol-cova/gessi/components`: SSR-safe component registration.
- `@pol-cova/gessi/gessi.js`: CDN entry that loads sibling CSS.
## SSR and First Paint
For server-rendered pages, link the stylesheet in `` so custom elements have fallback styling before JavaScript runs:
```html
...
```
Gessi applies declared `theme`, `background`, `pattern`, `pattern-color`, and `pattern-size` attributes in CSS before enhancement, so the first paint matches the final desktop theme instead of the library's pink page defaults.
When `` is present, the page background falls back to neutral dark chrome. You can still override `body` styles for full-viewport desktops.
Typed CSS `attr()` maps custom `background` values on first paint in current Chromium and Safari. Very old browsers still get the correct theme defaults and patterns, but custom background colors may wait until `gessi.js` runs.
See `examples/ssr-desktop.html` for a minimal fixture.
## Design Rules
- Plain HTML is the public API.
- Keep content in light DOM.
- Use semantic elements inside components.
- Do not add React, Vue, or another framework only to use Gessi.
- Use Gessi for reusable chrome, system UI, media effects, and interaction.
- Keep project-specific grids and page layout in your own CSS.
- Make narrow screens readable without duplicate mobile markup.
## Visual Systems
Set `data-gs-style` on any page region:
```html
...
```
Set `theme` on a desktop:
```html
...
```
Built-in styles:
- `neo`
- `minimal`
- `retro`
- `old-tech`
- `classic-os`
- `custom`
## Custom Theme Tokens
Use `theme="custom"` or `data-gs-style="custom"`, then set public tokens on the same element.
Common tokens:
- `--gs-ink`: primary text and foreground color.
- `--gs-paper`: base surface color.
- `--gs-line`: border and keyline color.
- `--gs-blue`, `--gs-mint`, `--gs-tomato`, `--gs-sun`: accent palette.
- `--gs-radius`: shared corner radius.
- `--gs-border-width`: shared border thickness.
- `--gs-shadow`, `--gs-shadow-sm`: elevation.
- `--gs-window-bg`, `--gs-window-title-bg`, `--gs-window-body-bg`: window surfaces.
- `--gs-toolbar-bg`, `--gs-control-bg`, `--gs-control-text`: menus, toolbars, and controls.
- `--gs-focus`: focus outline color.
Example:
```html
...
```
## Desktop Layout Persistence
Add `storage-key` to opt into localStorage-backed layout persistence:
```html
...
```
Public methods:
- `serializeLayout()`: returns JSON-safe state.
- `restoreLayout(layout)`: applies trusted state and returns `true` or `false`.
- `resetLayout()`: clears the stored key.
Restore events:
- `gs-layout-restore-before`: cancelable.
- `gs-layout-restore-after`: fires after restore.
## Bundled Pixel Icons
Fifteen original 32px SVG icons ship under `@pol-cova/gessi/icons/*`.
Use them with `gessi-icon` for a labeled desktop icon, or with a native `img`
when the image itself conveys information.
```html
```
## Markdown Content
Wrap generated Markdown HTML in `gessi-document` or `.gs-prose`.
```html
6 min read
Release notes
Rendered Markdown stays semantic.
Note
This is useful for MDX callouts.
```
Supported Markdown output includes headings, paragraphs, lists, tables, blockquotes, code blocks, footnotes, task lists, images, figures, details, and links.
## Component Families
Environment:
- `gessi-desktop`
- `gessi-window`
- `gessi-dialog`
Navigation:
- `gessi-menu`
- `gessi-toolbar`
- `gessi-dock`
- `gessi-breadcrumb`
- `gessi-tabs`
- `gessi-icons`
- `gessi-icon`
- `gessi-tree`
- `gessi-list`
System UI:
- `gessi-panel`
- `gessi-meter`
- `gessi-alert`
- `gessi-toast`
- `gessi-tooltip`
- `gessi-separator`
Content and forms:
- `gessi-timeline`
- `gessi-entry`
- `gessi-form`
- `gessi-load-more`
## Server-Rendered Content and Forms
`gessi-timeline` and `gessi-entry` provide a semantic chronological list. They
do not fetch data: render a complete page normally and return `gessi-entry`
fragments for an HTMX request when desired. `gessi-load-more` styles a normal
link or button, so pagination works without JavaScript.
`gessi-form` is a layout wrapper inside a real `form`. It accepts `columns`
(default `1`) and `compact`. Keep native `label`, `input`, `select`, `textarea`,
and `button` elements inside it; Flask actions, methods, CSRF inputs, and HTMX
attributes are preserved.
```html
```
Media:
- `gessi-media`
- `gessi-map`
- `gessi-marker`
- `gessi-carousel`
## Image Effects
Use `effect` on `gessi-media` or `gessi-map`.
```html
```
Effects compose by space-separated name.
## Accessibility support matrix
Gessi's interactive components are covered in Chromium, Firefox, and WebKit.
Keyboard coverage includes menus, tabs, carousels, dialogs, desktop window
cycling, generated controls, reduced-motion styles, and no-JavaScript content.
Use current versions of VoiceOver with Safari, NVDA with Firefox or Chrome, and
JAWS with Chrome or Edge for manual screen-reader verification. Screen readers
and browsers update independently, so test the combinations used by your
audience before releasing an application.
## Static Frameworks
Astro:
```astro
---
import "@pol-cova/gessi/css";
---
```
Plain static generators can copy:
```txt
node_modules/@pol-cova/gessi/dist/gessi.css
node_modules/@pol-cova/gessi/dist/gessi.js
```
## AI Agent Prompt
Use this prompt as a starting point:
```txt
Build this page with Gessi.
Use @pol-cova/gessi/css and @pol-cova/gessi/components in bundlers, or the CDN gessi.js entry in plain HTML.
Keep content semantic and in light DOM. Use Gessi components for reusable chrome: desktop, windows, dialogs, menus, toolbars, docks, panels, alerts, media, maps, and carousels. Keep project-specific layout in scoped CSS.
Do not add a framework runtime only to use Gessi. Use native links for navigation and native buttons for actions. Preserve keyboard access, focus-visible states, alt text, contrast, long-content handling, and responsive flow below 720px.
```