BEFORE YOU START

Neo requires the TrueShade component — it backs light/dark persistence and the library cannot function without it. Install it first.

Neo is built for desktop. Below 1040px the layout enforces horizontal scrolling.

INSTALLATION

1. Install TrueShade from Forge.

2. Install Neo Design System.

3. In your application, add NeoDesignSystem and TrueShade as dependencies.

4. Set NeoBase as your application's theme.

That is the whole setup. There is no OnApplicationReady hook to wire, no body class and no data attribute to set by hand — AppShell handles all of it.

BUILDING YOUR FIRST SCREEN

AppShell is the outermost wrapper. It takes no input parameters and self-initialises: its OnReady places the TrueShade block and starts the shell for you.

1. Place AppShell on your screen. It gives you three placeholders: Header, Aside and Content.

2. Put ShellHeader in the Header placeholder.

3. Put ShellAside in the Aside placeholder.

4. Put Layout_Neo in the Content placeholder.

5. Build your page inside Layout_Neo's Content placeholder.

Do not call InitShell yourself when using AppShell — it is already called on ready with the aside expanded.

ShellHeader placeholders: Portfolio, PortfolioOverlay, ExpandToggle, Buttons, AdditionalBlocks, Avatar, LoginOverlay.

ShellAside placeholders: Primary, Secondary, HeaderIcon, HeaderIconLeft, HeaderTitle, HeaderIconRight. Input: SecondaryOpen (Boolean, default True).

Layout_Neo placeholders: Header, TopInfo, Content. Inputs: ScrollType (Text, default "page"), LayoutType (Text), ReserveSidePanelSpace (Boolean).

SIDEBAR NAVIGATION

Build the sidebar inside ShellAside's Primary placeholder.

Use AsideItem for a navigation entry. Inputs: Label, IsActive, Level, IsOpen, HasChildren, HasIcon, ParentId, Section. It raises OnClick. Level 0 is a section header with an optional expand arrow; level 1 is a leaf link.

Use AsideSection for a collapsible group. It wraps an AsideItem header plus an animated grid that shows and hides its children. Inputs: Label, SectionId, IsOpen, IsActive, HasIcon, Section.

To control the sidebar from your own code, call ToggleAside. ShellAside adds the is-aside-expanded class to the body automatically.

THEME SWITCHING

Neo Design System ships light and dark. TrueShade persists the user's choice and applies it as a data-theme attribute on the root element.

- SetTheme(Theme) — apply "light", "dark" or "system-default".

- GetTheme() — returns the scheme actually in effect. "system-default" is resolved to the real operating system preference, so you always get "light" or "dark" back.

- ToggleTheme() — switch between light and dark.

- UseSystemTheme() — follow the operating system preference.

AppShell exposes an OnThemeChange event with two Text outputs: Raw (what the user selected, which may be "system-default") and Effective (what is actually rendered). Handle it when a component needs to react to a theme change — recolouring a chart, for instance.

InitTheme exists only for backwards compatibility and does nothing once the theme system is initialised. Use AppShell instead.

STYLING STANDARD WIDGETS

Most of Neo's surface is CSS classes applied to standard OutSystems widgets, not blocks. Apply these to get Neo styling:

- Button: btn. Variants: btn btn-primary, btn btn-destructive, btn btn-ghost.

- Input: form-control. Add not-valid for the validation error state.

- Dropdown or Select: dropdown, on an element carrying the data-dropdown attribute. Variants: dropdown-small, dropdown-large, dropdown-ghost, dropdown-btn.

- Table: table on the table, table-header on the header row, table-row on data rows.

READY-MADE BLOCKS

Beyond the shell, Neo Design System ships:

- Avatar — user initials in a coloured circle or square. Inputs: Initials (mandatory), Color, Format, Size, Label.

- Badge — status badge with semantic colour variants. Inputs: Label (mandatory), Variant (default "neutral").

- SearchInput — a search-styled input.

- Pagination — page navigation, with keyboard and screen-reader support.

- DropdownEmpty and DropdownItem — a floating menu panel and its rows. Keyboard and screen-reader accessible, dismisses on click-outside and on Escape, and positions itself to stay inside the viewport. DropdownEmpty inputs: IsOpen, PopoverWidth, ExtendedClass, TriggerLabel, with Trigger and Content placeholders. DropdownItem input: Title (mandatory).

- Skeleton, SkeletonBox and SkeletonTable — loading placeholders.

- Section — a content section wrapper.

- Icon and IconSprite — see Icons above.

USING DESIGN TOKENS

Neo Design System defines 612 design tokens covering colour, typography, spacing and sizing, elevation, motion and layout, with 277 dark-mode overrides.

Reference them from your own CSS with var(--token-name) rather than hardcoding values. Anything built on the tokens stays correct in both light and dark, and follows the design language when it moves. Tokens are the intended extension point: if a component you need does not ship as a block, build it against the tokens and it will match everything else.

GOOD TO KNOW

- There are no blocks for checkbox, radio, textarea, date picker, modal or tabs. Use standard widgets with the CSS classes above.

- No right-to-left support.

- Explicit keyboard and ARIA handling is implemented in DropdownEmpty and Pagination. Verify other blocks against your own accessibility requirements.

- This is an early alpha.