# NDS - Vanilla National Design System

> An open-source, vanilla implementation of Saudi Arabia's National Design System. Production-ready HTML, CSS, and JavaScript built from scratch with zero dependencies.

A framework-free build of the design language the Saudi [Digital Government Authority (DGA)](https://dga.gov.sa/) uses to unify government websites and services. It covers every UI component, a layout system, page templates, and full documentation — RTL (Arabic) first, with LTR (English) support.

Important notes:

- **Plain HTML/CSS/JS, zero runtime dependencies.** Works with any stack — or none — and is *not* tied to React, Vue, Svelte, or any framework. A smart loader detects the components present on each page and initializes only those.
- **Markup is a contract.** Every component page below ships canonical, copy-ready HTML in a `lang-html` code block alongside live demos. Copy that markup verbatim — class names, element nesting, `data-*` attributes, and ARIA roles all matter. Do not infer or invent structure.
- **RTL is the default.** Styles use CSS logical properties, so direction flips from a single `dir`/`lang` attribute — there is no separate RTL stylesheet.
- **Composition.** Pages are built from sections and a responsive grid (see *Layout*). The *Document head* (under *UI shell*) lists the stylesheets and scripts every page must load.
- **Theming.** Styling uses a 4-tier design-token system (palette → primitives → semantic → component) as CSS custom properties. Light/dark mode and full re-branding work from a single `data-theme` attribute — OKLCH-seed palettes, predefined themes, or stylesheet themes — with no rebuild.
- **Not government-only.** NDS is a general-purpose design system — any website can adopt it by re-theming to its own brand (generate a palette from a `data-theme` seed or override the tokens) and swapping the logos. The *default* identity (tokens, colors, logos, and the DGA digital-stamp) is reserved for Saudi Arabia government entities, so non-government use must replace those before deploying — see the [README disclaimer](https://github.com/mazin-musleh/NDS-vanilla#disclaimer).
- **Tech tags** after each component show what it needs: `CSS` (style only), `JS` (requires the bundled script), `API`/`Data` (consumes data or a remote endpoint), `Add-on` (optional bundle).

## Guides

- [Get started](https://mazin-musleh.github.io/NDS-vanilla/guides/get-started.html): Adopting NDS into an existing project with a coding agent — download the template release, install NDS IQ (a rules file at the project root, plus a short anchor in the project's `CLAUDE.md`/`AGENTS.md`), set the two paths the anchor declares, then work session by session.
- [NDS IQ](https://mazin-musleh.github.io/NDS-vanilla/guides/integration-quality.html): The instruction system itself — how it is built, tested, versioned, and kept current, with the full revision history.
- [NDS IQ rules (raw)](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_includes/NDS-IQ.md): The installable rules file, latest published revision — download the raw file itself (curl or equivalent, never a summarizing web-fetch: a re-rendered copy is corrupt), save it as `NDS-IQ.md` at the project root, then follow its own "Install and upgrade this file" section, which adds the anchor to the agent instruction file. Read it top to bottom, once per session, before any NDS work.

## Foundations
- [Icons](https://mazin-musleh.github.io/NDS-vanilla/components/icons.html): The HugeIcons Stroke Rounded font for content plus a curated inline SVG set for components and chrome, with sizing, color, and license guidance (CSS) **Use when:** How icons work here: the HugeIcons font for page content, plus the curated inline SVG set for components and chrome, with sizing, colour, and licence guidance. Read before adding any icon.
- [Themes](https://mazin-musleh.github.io/NDS-vanilla/components/themes.html): Light and dark mode, plus brand theming: generate a full palette from OKLCH seed colours, or override the design tokens with a stylesheet theme (CSS, JS) **Use when:** Light and dark mode, plus brand theming: generate a full palette from OKLCH seed colours, or override the design tokens with a stylesheet. Read this before applying any brand colour. — source: [JS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_js/nds-theme.js)
- [Tokens](https://mazin-musleh.github.io/NDS-vanilla/components/tokens.html): Every CSS custom property in the system: palette, primitive scales, semantic meanings, and component dials to reference and override (CSS) **Use when:** Every CSS custom property in the system: palette, primitive scales, semantic meanings, and component dials. Read this before writing any hardcoded colour, spacing, or radius value.

## UI components
- [Accordion](https://mazin-musleh.github.io/NDS-vanilla/components/accordion.html): Expandable content panels with nested group support (JS, CSS, API) **Use when:** Expand and collapse panels in place: FAQ lists, collapsible sections, show-hide groups, disclosure widgets. Supports nested groups. To switch between panels in one space instead of expanding, use Tabs or Content Switcher. — source: [JS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_js/nds-accordion.js) · [SCSS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_sass/components/_accordion.scss)
- [Alert](https://mazin-musleh.github.io/NDS-vanilla/components/alert.html): Contextual messages for status, warnings, and notifications (JS, CSS, API) **Use when:** An inline status message sitting in the page: success, error, warning, or info banner, form-level feedback, a dismissible notice. For a blocking message over the page use Modal. — source: [JS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_js/nds-alert.js) · [SCSS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_sass/components/_alert.scss)
- [Avatar](https://mazin-musleh.github.io/NDS-vanilla/components/avatar.html): Profile images, initials, and group stacks (CSS) **Use when:** A user picture, profile photo, initials circle, or a stacked group of member avatars. — source: [SCSS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_sass/components/_avatar.scss)
- [Breadcrumb](https://mazin-musleh.github.io/NDS-vanilla/components/breadcrumb.html): Hierarchical path showing the current page location (JS, CSS, API) **Use when:** The path trail showing where the current page sits: breadcrumbs, hierarchy path, back-navigation trail. On template pages it is set from front matter, not hand-written. — source: [JS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_js/nds-breadcrumb.js) · [SCSS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_sass/components/_breadcrumb.scss)
- [Buttons](https://mazin-musleh.github.io/NDS-vanilla/components/button.html): Interactive actions with multiple variants, sizes, and states (CSS) **Use when:** Any clickable action: primary, secondary, destructive, subtle, and icon-only variants, with sizes and states. The base for most interactive markup. — source: [SCSS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_sass/components/_buttons.scss)
- [Cards](https://mazin-musleh.github.io/NDS-vanilla/components/cards.html): Versatile content containers for articles, profiles, and actions (CSS) **Use when:** A boxed content container: article teasers, profile cards, service tiles, dashboard panels, grid items. The default building block for any card grid or listing. — source: [SCSS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_sass/components/_cards.scss)
- [Chips](https://mazin-musleh.github.io/NDS-vanilla/components/chips.html): Compact labels for tags, filters, and selections (CSS) **Use when:** Small pills the user acts on: removable filter chips, selected-value chips, choice chips. For read-only labels use Tags; for a field that turns typed text into chips use Tag Input. — source: [SCSS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_sass/components/_chips.scss)
- [Code](https://mazin-musleh.github.io/NDS-vanilla/components/code.html): Formatted code blocks with syntax highlighting and copy (JS, CSS, API) **Use when:** Show source code on the page: syntax-highlighted code blocks, snippets, a copy-to-clipboard code sample. — source: [JS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_js/nds-code.js) · [SCSS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_sass/components/_code.scss)
- [Content Switcher](https://mazin-musleh.github.io/NDS-vanilla/components/content-switcher.html): Toggle between content sections within the same space on the screen (JS, CSS, API) **Use when:** Toggle between content sections in the same space with a segmented control: view switcher, list-versus-grid toggle, segmented buttons. Same engine as Tabs; choose Tabs when the control should read as a tab strip. — source: [JS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_js/nds-tabs.js) · [SCSS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_sass/components/_content-switcher.scss)
- [Cooldown Button](https://mazin-musleh.github.io/NDS-vanilla/components/cooldown-button.html): Click-disabled countdown button for resend, retry, and rate-limited actions (JS, CSS, API) **Use when:** A button that disables itself and counts down before it can be pressed again: resend OTP, resend email, retry, or any rate-limited action. — source: [JS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_js/nds-cooldown-button.js) · [SCSS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_sass/components/_cooldown-button.scss)
- [Definition List](https://mazin-musleh.github.io/NDS-vanilla/components/definition-list.html): Structured key-value pairs in grid or list layouts (CSS) **Use when:** Key-value pairs in a grid or list: detail views, summary panels, specification tables, review-your-answers screens, profile field lists. — source: [SCSS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_sass/components/_definition-list.scss)
- [Drawer](https://mazin-musleh.github.io/NDS-vanilla/components/drawer.html): Collapsible navigation lists with accordion groups (JS, CSS, API) **Use when:** A vertical list container for sidebar navigation, submenus, quick links, and inline notifications, in compact or expanded layouts. For a surface that slides in over the page use Panels; for the main collapsible sidebar use Side Menu. — source: [JS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_js/nds-drawer.js) · [SCSS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_sass/components/_drawer.scss)
- [Dropmenu](https://mazin-musleh.github.io/NDS-vanilla/components/dropmenu.html): Toggle-activated overlay for actions and navigation (JS, CSS, API) **Use when:** A menu opened from a trigger: dropdown menu, action menu, kebab or overflow menu, context actions, a sort or filter popover. The shared engine behind most NDS menus. — source: [JS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_js/nds-dropmenu.js) · [SCSS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_sass/components/_dropmenu.scss)
- [Empty](https://mazin-musleh.github.io/NDS-vanilla/components/empty.html): Parent-adaptive placeholder for containers with no content (JS, CSS, API) **Use when:** The no-data state: empty table, no search results, zero state, nothing-here placeholder. Adapts its markup to the parent container. — source: [JS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_js/nds-empty.js) · [SCSS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_sass/components/_empty.scss)
- [Featured Icons](https://mazin-musleh.github.io/NDS-vanilla/components/featured-icons.html): Decorative icon containers with shape and color options (CSS) **Use when:** A decorative icon in a shaped container: circled icons on cards, feature-list bullets, step icons, support-channel tiles. — source: [SCSS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_sass/components/_featured-icons.scss)
- [Feedback Icons](https://mazin-musleh.github.io/NDS-vanilla/components/feedback-icons.html): Semantic status icons for success, error, and info (CSS) **Use when:** Small semantic status icons for success, error, and info states. — source: [SCSS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_sass/components/_feedback-icons.scss)
- [Floating Action Button](https://mazin-musleh.github.io/NDS-vanilla/components/fab.html): FAB that pins to a viewport corner and stacks with others (JS, CSS, API) **Use when:** A button pinned to a corner of the viewport: FAB, floating add button, back-to-top, or a stack of quick actions. — source: [JS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_js/nds-fab.js) · [SCSS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_sass/components/_fab.scss)
- [Image Popup Viewer](https://mazin-musleh.github.io/NDS-vanilla/components/ipv.html): IPV fullscreen image preview with zoom and navigation (JS, CSS, API) **Use when:** Click an image to open it fullscreen: lightbox, image preview, gallery viewer, with zoom and next and previous navigation. — source: [JS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_js/nds-ipv.js) · [SCSS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_sass/components/_ipv.scss)
- [Link](https://mazin-musleh.github.io/NDS-vanilla/components/link.html): Inline navigation with color variants and automatic external-link detection (CSS, JS) **Use when:** An inline text link with colour variants, and automatic detection and marking of external links. — source: [JS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_js/nds-link.js) · [SCSS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_sass/components/_link.scss)
- [Loading](https://mazin-musleh.github.io/NDS-vanilla/components/loading.html): Spinners and skeleton placeholders for loading states (CSS) **Use when:** Loading states: spinner, skeleton placeholder, shimmer, or a busy indicator while content is fetched. For a container that finished loading with nothing in it use Empty. — source: [SCSS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_sass/components/_loading.scss)
- [Modal](https://mazin-musleh.github.io/NDS-vanilla/components/modal.html): Focused dialog overlays for confirmations and forms (JS, CSS, API) **Use when:** A dialog over the page: modal, popup, confirmation prompt, a form in an overlay, a delete confirmation. For a surface that slides in from an edge use Panels. — source: [JS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_js/nds-modal.js) · [SCSS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_sass/components/_modal.scss)
- [Pagination](https://mazin-musleh.github.io/NDS-vanilla/components/pagination.html): Page-by-page navigation for large data sets (JS, CSS, API) **Use when:** Page-by-page navigation for long lists and tables, with a per-page picker. Pairs with Tables and Filter. — source: [JS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_js/nds-pagination.js) · [SCSS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_sass/components/_pagination.scss)
- [Panels](https://mazin-musleh.github.io/NDS-vanilla/components/panels.html): Content-agnostic surface that slides in from any edge of the viewport (JS, CSS, API) **Use when:** A surface that slides in from any edge of the viewport: slide-over, off-canvas panel, side sheet, detail panel, filter panel. For a dialog centred over the page use Modal; for a sidebar navigation list use Drawer. — source: [JS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_js/nds-panels.js) · [SCSS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_sass/components/_panels.scss)
- [Persona](https://mazin-musleh.github.io/NDS-vanilla/components/persona.html): Identity block with avatar, name, role, and optional action row (CSS) **Use when:** An identity block: avatar with name, role, and an optional row of actions. Use for user menus, author bylines, contact cards, and team member entries. — source: [SCSS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_sass/components/_persona.scss)
- [Progress](https://mazin-musleh.github.io/NDS-vanilla/components/progress.html): Visual indicators for task completion and loading (JS, CSS, API) **Use when:** Show completion: progress bar, percentage indicator, upload progress. For labelled step-by-step stages use Stepper. — source: [JS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_js/nds-progress.js) · [SCSS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_sass/components/_progress.scss)
- [Quote](https://mazin-musleh.github.io/NDS-vanilla/components/quote.html): Semantic quotation block with optional title and author attribution (CSS) **Use when:** A pulled quotation block, with an optional title and author attribution. — source: [SCSS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_sass/components/_quote.scss)
- [Rating](https://mazin-musleh.github.io/NDS-vanilla/components/rating.html): Star-based display and input for user ratings (JS, CSS, API) **Use when:** Star ratings, both read-only display and user input. — source: [JS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_js/nds-rating.js) · [SCSS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_sass/components/_rating.scss)
- [Scroll More](https://mazin-musleh.github.io/NDS-vanilla/components/scroll-more.html): Overflow wrapper with edge mask-fade and sticky show-more button (JS, CSS, API) **Use when:** Wrap content that overflows its container: a scrollable region with faded edges and a sticky show-more button. Auto-detects whether it scrolls horizontally or vertically. — source: [JS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_js/nds-scroll-more.js) · [SCSS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_sass/components/_scroll-more.scss)
- [Stepper](https://mazin-musleh.github.io/NDS-vanilla/components/stepper.html): Sequential step indicators for multi-stage workflows (JS, CSS, API) **Use when:** Show progress through a multi-stage flow: step indicator, wizard progress, numbered stages. For a plain percentage bar use Progress. — source: [JS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_js/nds-stepper.js) · [SCSS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_sass/components/_stepper.scss)
- [Swiper](https://mazin-musleh.github.io/NDS-vanilla/components/swiper.html): Touch-enabled carousel for images and content slides (JS, CSS, API) **Use when:** A carousel or slideshow: touch-enabled image slider, content slides, testimonial rotator. — source: [JS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_js/nds-swiper.js) · [SCSS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_sass/components/_swiper.scss)
- [TOC](https://mazin-musleh.github.io/NDS-vanilla/components/toc.html): Auto-populated in-page table of contents with active-section tracking (JS, CSS, API) **Use when:** An auto-built on-this-page table of contents that tracks the active section while the user scrolls. Use on long articles, policies, and guides. — source: [JS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_js/nds-toc.js) · [SCSS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_sass/components/_toc.scss)
- [Tabs](https://mazin-musleh.github.io/NDS-vanilla/components/tabs.html): Switchable content panels with horizontal tab navigation (JS, CSS, API) **Use when:** Switch between panels of content with a tab strip, without leaving the page. For a segmented-control look use Content Switcher; to expand panels in place instead of switching use Accordion. — source: [JS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_js/nds-tabs.js) · [SCSS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_sass/components/_tabs.scss)
- [Tags](https://mazin-musleh.github.io/NDS-vanilla/components/tags.html): Small labels for categorization and metadata (CSS) **Use when:** Small read-only labels: status badges, category labels, metadata pills. For labels the user can remove or click use Chips. — source: [SCSS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_sass/components/_tags.scss)
- [Toolbar](https://mazin-musleh.github.io/NDS-vanilla/components/toolbar.html): Controls bar above a table, list, or grid: result counts and applied filters lead, export and actions trail (CSS) **Use when:** The controls bar above a table, list, or grid: result counts and applied filters lead, search, export, and actions trail. Use it so every data screen shares one layout. — source: [SCSS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_sass/components/_toolbar.scss)
- [Tooltip](https://mazin-musleh.github.io/NDS-vanilla/components/tooltip.html): Click-activated balloon for contextual help next to a term or field (JS, CSS, API) **Use when:** A small balloon of help text beside a term or field, opened on click. — source: [JS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_js/nds-tooltip.js) · [SCSS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_sass/components/_tooltip.scss)

## Form components
- [Autocomplete](https://mazin-musleh.github.io/NDS-vanilla/components/autocomplete.html): Type-ahead search with filtered suggestions (JS, CSS, API) **Use when:** A type-ahead field: search suggestions, live search, combobox, async option loading, city or name lookup. Carries the search-box markup too. To pick several values use Multiselect; for free typed values use Tag Input. — source: [JS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_js/nds-autocomplete.js) · [SCSS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_sass/components/_autocomplete.scss)
- [Checkbox](https://mazin-musleh.github.io/NDS-vanilla/components/checkbox.html): Multi-select toggles for options and preferences (CSS) **Use when:** Multi-select toggles: checkbox groups, opt-in boxes, terms agreement, filter option lists. — source: [SCSS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_sass/components/_checkbox.scss)
- [Custom Select](https://mazin-musleh.github.io/NDS-vanilla/components/forms.html#customSelect): Styled single-choice dropdown with custom option markup and a JS API, built on dropmenu (JS, CSS, API) **Use when:** A styled single-choice dropdown built on Dropmenu, for any select a native one cannot style: custom option markup, icons or descriptions in options, and a JS API (NDS.CustomSelect.create, .setValue, .clear, plus a change event). Documented inside the Forms page. The default for any in-form choice field, whatever the option count — small fixed lists included. For type-ahead search use Autocomplete; for several choices use Multiselect; use Selects only when the dev, knowing this default, wants the browser's native control. — source: [JS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_js/nds-customselect.js) · [SCSS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_sass/components/_forms.scss)
- [Date Picker](https://mazin-musleh.github.io/NDS-vanilla/components/date-picker.html): Hijri/Gregorian calendar with dual date conversion (JS, CSS, API) **Use when:** Any date field: calendar picker, date range, Hijri or Gregorian selection, date of birth, appointment booking. Converts between both calendars. — source: [JS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_js/nds-date-picker.js) · [SCSS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_sass/components/_date-picker.scss)
- [Editor](https://mazin-musleh.github.io/NDS-vanilla/components/editor.html): Rich text field that submits clean NDS markup, converting Word, Google Docs, and web pastes and inserting NDS components as blocks (JS, CSS, API, {"name"=>"Beta", "style"=>"nds-yellow"}) **Use when:** A rich text editor or WYSIWYG field. Submits clean NDS markup and converts pastes from Word, Google Docs, and web pages. Use it to replace TinyMCE, CKEditor, Quill, or similar. — source: [JS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_js/nds-editor.js) · [SCSS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_sass/components/_editor.scss)
- [File Upload](https://mazin-musleh.github.io/NDS-vanilla/components/upload.html): Drag-and-drop file input with preview and validation (JS, CSS, API) **Use when:** Any file input: drag-and-drop upload, attachment field, document upload, image picker, with preview and validation. — source: [JS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_js/nds-upload.js) · [SCSS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_sass/components/_upload.scss)
- [Multiselect](https://mazin-musleh.github.io/NDS-vanilla/components/multiselect.html): Multi-option select over a native checkbox group: removable chips, JSON-populated options, staged or instant commit (JS, CSS, API) **Use when:** Pick several options from a list: multi-select dropdown, checkbox dropdown, grouped option lists, selections shown as removable chips. Submits natively as a checkbox array. For free typed values use Tag Input; for one choice use Custom Select. — source: [JS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_js/nds-multiselect.js) · [SCSS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_sass/components/_multiselect.scss)
- [Number Input](https://mazin-musleh.github.io/NDS-vanilla/components/forms.html#numberInput): Numeric field with increment and decrement controls, min/max, and step (JS, CSS) **Use when:** A numeric field with plus and minus controls, min, max, and step: quantity picker, spinner, numeric stepper. — source: [JS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_js/nds-forms.js) · [SCSS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_sass/components/_forms.scss)
- [OTP Input](https://mazin-musleh.github.io/NDS-vanilla/components/otp.html): Segmented one-time password fields with auto-advance (JS, CSS, API) **Use when:** Segmented one-time code fields with auto-advance: OTP, verification code, PIN entry, two-factor code. Pair with Cooldown Button for the resend action. — source: [JS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_js/nds-otp.js) · [SCSS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_sass/components/_otp.scss)
- [Password](https://mazin-musleh.github.io/NDS-vanilla/components/password.html): Password field with live strength rules and confirm-match checking (JS, CSS, API) **Use when:** Choosing a new password: sign-up, change password, password reset. Rule chips update per keystroke and block submit until they pass. Pair with Text Fields for the rest of the form. — source: [JS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_js/nds-password.js) · [SCSS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_sass/components/_password.scss)
- [Radio](https://mazin-musleh.github.io/NDS-vanilla/components/radio.html): Single-choice selection within a group (CSS) **Use when:** Single-choice selection within a group: radio buttons, either-or options, one-of-many questions. — source: [SCSS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_sass/components/_radio.scss)
- [Selects](https://mazin-musleh.github.io/NDS-vanilla/components/forms.html): Native dropdown menus for choosing from a list (JS, CSS) **Use when:** A single-choice dropdown rendered by the browser itself — only when the dev explicitly wants the native control (the OS picker on mobile). In-form choice fields default to Custom Select, whatever the option count: a native select beside styled NDS fields breaks the form's look. If the dev suggests a plain select to keep things simple, offer Custom Select first; use native only if the dev still wants it. For type-ahead search use Autocomplete; for several choices use Multiselect. — source: [JS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_js/nds-forms.js) · [SCSS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_sass/components/_forms.scss)
- [Slider](https://mazin-musleh.github.io/NDS-vanilla/components/slider.html): Numeric range input with single-thumb and dual-thumb modes for picking a value or a min–max span (JS, CSS, API) **Use when:** A range input dragged along a track: a single value, or dual thumbs for a min-max span such as a price or date range. — source: [JS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_js/nds-slider.js) · [SCSS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_sass/components/_slider.scss)
- [Switch](https://mazin-musleh.github.io/NDS-vanilla/components/switch.html): Binary on/off toggles for settings and preferences (CSS) **Use when:** A binary on-off toggle for a setting or preference. For switching between two content views use Content Switcher. — source: [SCSS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_sass/components/_switch.scss)
- [Tag Input](https://mazin-musleh.github.io/NDS-vanilla/components/taginput.html): Free-text tags committed as removable chips while typing, posted natively as an array (JS, CSS, API) **Use when:** A field where typed free text becomes removable chips, committing on Enter or comma and submitting natively as an array. Use for keywords, skills, or email recipients. To pick from a fixed list instead use Multiselect. — source: [JS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_js/nds-taginput.js) · [SCSS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_sass/components/_taginput.scss)
- [Text Inputs](https://mazin-musleh.github.io/NDS-vanilla/components/forms.html): Single-line fields with labels, icons, and validation (JS, CSS) **Use when:** Single-line form fields with labels, icons, helper text, and validation states. The base for most form work. — source: [JS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_js/nds-forms.js) · [SCSS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_sass/components/_forms.scss)
- [Textareas](https://mazin-musleh.github.io/NDS-vanilla/components/forms.html#textareaInput): Resizable multi-line text fields (JS, CSS) **Use when:** A resizable multi-line text field for comments, messages, and descriptions. — source: [JS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_js/nds-forms.js) · [SCSS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_sass/components/_forms.scss)
- [User Feedback](https://mazin-musleh.github.io/NDS-vanilla/components/user-feedback.html): Satisfaction surveys and inline rating forms (JS, CSS) **Use when:** Ask the user what they think: satisfaction survey, was-this-helpful widget, inline rating form, feedback prompt. — source: [JS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_js/nds-user-feedback.js) · [SCSS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_sass/components/_user-feedback.scss)
- [Voice Input](https://mazin-musleh.github.io/NDS-vanilla/components/voice-input.html): Voice-to-text button that dictates into a text field, with Arabic/English auto-detection (JS, API) **Use when:** A microphone button that dictates speech into a text field, detecting Arabic or English automatically. — source: [JS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_js/nds-voice-input.js)

## Data components
- [Chart](https://mazin-musleh.github.io/NDS-vanilla/components/chart.html): Lightweight SVG charts: bar, line, pie, and donut (JS, CSS, API) **Use when:** Data visualisation: bar, line, pie, and donut charts, graphs, plots. SVG-based with no charting library. For one number with a trend line use Metric. — source: [JS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_js/nds-chart.js) · [SCSS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_sass/components/_chart.scss)
- [Export](https://mazin-musleh.github.io/NDS-vanilla/components/export.html): Declarative CSV, Excel, and PDF downloads from any table, card list, or marked-up container (JS, CSS, API) **Use when:** Download what is on the page as a file: export to CSV or Excel, print or save a table as PDF, download a report. Works on any table, card list, or marked-up container, and honours the current selection and pagination. — source: [JS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_js/nds-export.js) · [SCSS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_sass/components/_export.scss)
- [Filter](https://mazin-musleh.github.io/NDS-vanilla/components/filter.html): Applied filters with search, URL sync, and remote data (JS, CSS, API) **Use when:** Narrow a list down: faceted filters, checkbox and range filters, applied-filter chips, URL-synced filtering, remote filtering. Pairs with Tables and Pagination on data screens. — source: [JS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_js/nds-filter.js) · [SCSS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_sass/components/_filter.scss)
- [Metric](https://mazin-musleh.github.io/NDS-vanilla/components/metric.html): Dashboard tile pairing a key statistic with an inline sparkline (CSS) **Use when:** A dashboard tile pairing one key number with an inline sparkline, so a value and its trend read at a glance. For full charts use Chart. — source: [SCSS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_sass/components/_metric.scss)
- [Selection](https://mazin-musleh.github.io/NDS-vanilla/components/selection.html): Selected-items counter for tables, card grids, and checkbox lists, with a records-line swap while a selection is active (JS, API) **Use when:** Show how many items are selected: a 5-selected-of-48 counter, select-all state, or a bulk-action bar over tables, card grids, and any checkbox list. — source: [JS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_js/nds-selection.js)
- [Sort](https://mazin-musleh.github.io/NDS-vanilla/components/sort.html): DOM-reorder engine for lists, grids, and tables with type auto-detect and URL sync (JS, API) **Use when:** Reorder items already in the DOM: sortable table columns, a sort dropdown over a card grid, A-to-Z or newest-first ordering, with type auto-detect and URL sync. This is the engine Tables sorting uses; call it directly for lists and grids. — source: [JS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_js/nds-sort.js)
- [Tables](https://mazin-musleh.github.io/NDS-vanilla/components/tables.html): Data grids with sorting, pagination, and expandable rows (JS, CSS, API) **Use when:** Any tabular data: data grid, data table, sortable table, expandable sub-rows, column visibility, records list. The starting point for replacing DataTables, jTable, ag-Grid, or a similar plugin. Pair it with Filter, Pagination, Sort, Selection, and Export; the Manage Records example shows all of them working together. — source: [JS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_js/nds-tables.js) · [SCSS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_sass/components/_tables.scss)

## Layout
- [Block](https://mazin-musleh.github.io/NDS-vanilla/layout/block.html): Spacing unit for content and block components inside a section body, with an optional title (CSS) **Use when:** Space out the parts of a section body. Put it straight on a block component such as a stepper, tab set, or table to give it the standard gap, or wrap paragraphs, lists, and tables that belong together under one optional heading. Use when content needs separation, or a heading, but not its own Section. — source: [SCSS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_sass/layout/_block.scss)
- [Flex](https://mazin-musleh.github.io/NDS-vanilla/layout/flex.html): Quick alignment, direction, and wrapping with custom-property overrides (CSS) **Use when:** Quick alignment, direction, and wrapping without writing CSS: row or column layouts, centering, spacing between items. — source: [SCSS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_sass/layout/_flex.scss)
- [Grid](https://mazin-musleh.github.io/NDS-vanilla/layout/grid.html): Responsive column system with flexible breakpoints (CSS) **Use when:** A responsive column layout: card grids, two, three, or four column sections, breakpoint-driven column counts. The default for laying out repeated items. — source: [SCSS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_sass/_grid.scss)
- [Page Shell](https://mazin-musleh.github.io/NDS-vanilla/layout/page-shell.html): The body structure every page shares, with the classes that switch chrome shape (CSS) **Use when:** Build the page skeleton before any content: the body structure, the chrome regions, and the classes that switch between the home, content page, minimal, and console shapes. Read this when you start a new page, pick a chrome shape, or mount a framework app inside NDS markup. It also names the two ways a page gets its chrome. A layout can inject the header, hero, and footer, which is what every page on this site does. Or the page composes them itself on the shell layout, so one file holds the whole page and its source reads as a complete document. Use the second when you want a standalone or full page in a single file, and copy the Home Page Template for it. — source: [SCSS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_sass/layout/_content-layout.scss)
- [Prose](https://mazin-musleh.github.io/NDS-vanilla/layout/prose.html): Default styling for classless flowing content from editors and CMSs (CSS) **Use when:** Style classless HTML you do not control: CMS output, rich text editor content, markdown, imported articles. Wrap it once and the headings, paragraphs, lists, quotes, and tables inside read correctly. — source: [SCSS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_sass/layout/_prose.scss)
- [Section](https://mazin-musleh.github.io/NDS-vanilla/layout/section.html): Page content sections with head, body, and action areas (CSS) **Use when:** The wrapper every page region uses, with head, body, and action areas. Read this before building any page: all NDS page content sits inside sections. — source: [SCSS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_sass/layout/_section.scss)
- [Status Section](https://mazin-musleh.github.io/NDS-vanilla/layout/status-section.html): Whole-page or inline outcome message with a status icon, a title, and one action (CSS) **Use when:** Report one outcome on its own page or as a section: page not found, 404, 500, access denied, request submitted, thank-you or confirmation page, payment failed, order received, form sent. A centered icon or illustration over a title, a short message, and a way out. For a message inside a form or a page region use Alert; for a chip on its own use Feedback icons. — source: [SCSS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_sass/layout/_section-layout.scss)

## UI shell
- [Clock](https://mazin-musleh.github.io/NDS-vanilla/ui-shell/topbar.html#topbarWidgets): Real-time clock with Hijri/Gregorian date (JS, API) **Use when:** A live clock with Hijri and Gregorian date. One of the top bar widgets. — source: [JS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_js/nds-timeDate.js) · [SCSS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_sass/components/_topbar.scss)
- [DGA Digital Stamp](https://mazin-musleh.github.io/NDS-vanilla/ui-shell/topbar.html#dgaDigitalStamp): Government authority verification panel (JS, CSS) **Use when:** The government authority verification panel for the top bar. Government sites only; remove it on any site that does not hold that verification. — source: [JS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_js/nds-digitalStamp.js) · [SCSS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_sass/components/_DGAdigitalStamp.scss)
- [Document Head](https://mazin-musleh.github.io/NDS-vanilla/ui-shell/head.html): Critical CSS, deferred bundles, and the inline gate every page loads in its head (JS, CSS) **Use when:** What every page must load in its head: critical CSS, the deferred bundles, and the inline reveal gate. Read this before writing the first page of an integration; a page missing it renders unstyled.
- [Footer](https://mazin-musleh.github.io/NDS-vanilla/ui-shell/footer.html): Multi-column footer with light and green variants (CSS) **Use when:** The site footer: multi-column links, contact details, and legal links, in light or green variants. — source: [SCSS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_sass/components/_footer.scss)
- [Header](https://mazin-musleh.github.io/NDS-vanilla/ui-shell/header.html): The region at the top of the page where the top bar, digital stamp panel, and main navigation compose (CSS) **Use when:** How the top bar, the DGA digital stamp panel, and the main navigation compose into one header region, with the full structure tree. Layout-coupled, so copy it from a full template page rather than in isolation. For the navigation bar itself, its dropdown menus and its JS API, use Main Navigation. For the government branding strip use Top Bar.
- [Hero](https://mazin-musleh.github.io/NDS-vanilla/ui-shell/hero.html): Full-width page banners with slider and call-to-action (JS, CSS) **Use when:** The banner at the top of a page: page hero, sub-hero, homepage slider, title block with a call-to-action. Usually set from page front matter, so copy it from a built page. — source: [SCSS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_sass/components/_hero.scss)
- [Main Navigation](https://mazin-musleh.github.io/NDS-vanilla/ui-shell/mainnav.html): Primary navigation bar with branding, mega-menu dropdowns, utility actions, and a mobile drawer (JS, CSS, API) **Use when:** The primary navigation bar of a site: branding, top-level links, mega-menu dropdowns in column, row or multi-column layouts, utility actions, and the mobile hamburger drawer. Use for main nav, top nav, navbar, site navigation, primary menu, or mega menu requests. Documented on its own page, split out of Header. For section navigation inside a page tree use Side Menu. For the government branding strip above it use Top Bar. — source: [JS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_js/nds-mainnav.js)
- [Side Info](https://mazin-musleh.github.io/NDS-vanilla/ui-shell/sideinfo.html): Companion column for service details, progress, and in-page navigation (JS, CSS, API) **Use when:** The companion column beside main content: service details, progress, a contact card, in-page navigation. Layout-coupled, so copy it from a full template page rather than in isolation. — source: [JS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_js/nds-sideinfo.js) · [SCSS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_sass/components/_sideinfo.scss)
- [Side Menu](https://mazin-musleh.github.io/NDS-vanilla/ui-shell/sidemenu.html): Collapsible nested sidebar navigation (JS, CSS) **Use when:** The collapsible nested sidebar for section navigation, common on admin screens and documentation. Layout-coupled, so copy it from a full page. — source: [JS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_js/nds-sidemenu.js) · [SCSS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_sass/components/_sidemenu.scss)
- [Top Bar](https://mazin-musleh.github.io/NDS-vanilla/ui-shell/topbar.html): Government branding bar with date, weather, and dark mode toggle (JS, CSS) **Use when:** The government branding bar above the header, carrying the date, weather, and the dark mode toggle. — source: [SCSS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_sass/components/_topbar.scss)
- [Weather Widget](https://mazin-musleh.github.io/NDS-vanilla/ui-shell/topbar.html#topbarWidgets): Live weather display from GPS coordinates (JS, CSS, API) **Use when:** Live weather from GPS coordinates. One of the top bar widgets. — source: [JS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_js/nds-cityWeather.js) · [SCSS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_sass/components/_topbar.scss)

## Utilities
- [Content Placeholder](https://mazin-musleh.github.io/NDS-vanilla/utilities/content-placeholder.html): Dashed stand-in marking a region a real component will replace (CSS) **Use when:** A dashed stand-in marking a region a real component will fill later. Use while scaffolding so an unfinished area reads as deliberate rather than broken. — source: [SCSS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_sass/_utilities.scss)
- [Cookies](https://mazin-musleh.github.io/NDS-vanilla/components/cookies.html): Privacy-compliant cookie management banner (JS, CSS, API) **Use when:** A cookie consent banner, privacy notice, or GDPR-style acceptance bar. — source: [JS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_js/nds-cookies.js) · [SCSS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_sass/components/_cookie.scss)
- [Copy](https://mazin-musleh.github.io/NDS-vanilla/utilities/copy.html): One-click clipboard copy with checkmark feedback and screen reader announcement (JS, CSS, API) **Use when:** One-click copy to clipboard with a checkmark confirmation and a screen reader announcement. Use for reference numbers, links, codes, and IDs. — source: [JS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_js/nds-copy.js) · [SCSS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_sass/components/_copy.scss)
- [Counter Animation](https://mazin-musleh.github.io/NDS-vanilla/utilities/numbers.html#counterAnimation): Scroll-triggered animated counters that count up to a target value (JS) **Use when:** Numbers that count up to their value when scrolled into view: animated statistics, KPI counters, impact figures. — source: [JS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_js/nds-numbers.js)
- [Currency](https://mazin-musleh.github.io/NDS-vanilla/utilities/numbers.html#currencyFormat): SAR and international currency symbols appended automatically via data attribute (JS, CSS) **Use when:** Append a currency symbol automatically from a data attribute. Covers SAR and international symbols on prices, fees, and totals. — source: [JS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_js/nds-numbers.js)
- [Divider](https://mazin-musleh.github.io/NDS-vanilla/utilities/divider.html): Horizontal or vertical rule with optional centered label (CSS) **Use when:** A horizontal or vertical rule between content, with an optional centered label such as OR.
- [Expandable Content](https://mazin-musleh.github.io/NDS-vanilla/utilities/expandable-content.html): Show more/less toggle for long content blocks (JS, CSS) **Use when:** A show more and show less toggle on a long block of content. — source: [JS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_js/nds-expandable.js)
- [Helper Classes](https://mazin-musleh.github.io/NDS-vanilla/utilities/helpers.html): Single-purpose classes for your own markup: centering, spacing reset, direction isolation, brand text color, and notes (CSS) **Use when:** Single-purpose classes for your own markup: centering, spacing reset, direction isolation, brand text colour, and notes. Check here before writing a one-off CSS rule. — source: [SCSS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_sass/_utilities.scss)
- [Hidden](https://mazin-musleh.github.io/NDS-vanilla/utilities/hidden.html): Visibility utilities: the hidden attribute honored everywhere and band-exact responsive hiding with data-hidden (CSS) **Use when:** Hiding things: the hidden attribute honoured everywhere, plus breakpoint-exact responsive hiding with data-hidden. Use this instead of writing your own display-none rule. — source: [SCSS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_sass/_utilities.scss)
- [Numbers](https://mazin-musleh.github.io/NDS-vanilla/utilities/numbers.html): Locale-aware thousand separators for any number on the page (JS, API) **Use when:** Locale-aware thousand separators applied to any number already on the page. — source: [JS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_js/nds-numbers.js)
- [Saudi Cities](https://mazin-musleh.github.io/NDS-vanilla/utilities/saudi-cities.html): Bundled JSON dataset of 132 Saudi Arabian cities with bilingual names, drop-in for autocomplete and address flows (Data) **Use when:** A bundled dataset of 132 Saudi cities with Arabic and English names. Drop it into an autocomplete, a select, or an address form instead of sourcing your own list.
- [Share](https://mazin-musleh.github.io/NDS-vanilla/utilities/share.html): Social share dropmenu for X, LinkedIn, WhatsApp, and copy link (JS, CSS) **Use when:** Share this page: a social share menu for X, LinkedIn, and WhatsApp, plus copy link. — source: [JS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_js/nds-share.js) · [SCSS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_sass/components/_share.scss)
- [Truncate Text](https://mazin-musleh.github.io/NDS-vanilla/utilities/truncate-text.html): Line-clamped overflow with expand/collapse toggle (CSS) **Use when:** Clamp long text to a fixed number of lines, with an expand and collapse toggle.

## Add-ons
- [Accessibility](https://mazin-musleh.github.io/NDS-vanilla/components/accessibility.html): Site-wide panel for accessibility presets, typography tuning, and visual filters (JS, CSS, Add-on, API) **Use when:** The dev asks for an accessibility widget, a11y toolbar, font-size controls, high contrast mode, colour-blind filters, or a WCAG preferences panel. Site-wide floating panel, shipped as an optional add-on bundle gated by a site flag. — source: [JS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_js/nds-accessibility.js) · [SCSS](https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_sass/components/_accessibility.scss)

## Page templates

DGA-compliant full-page templates — copy, populate with your content, and publish.
- [Home Page Template](https://mazin-musleh.github.io/NDS-vanilla/templates/home-template.html): Organization home page with a main hero slider, headline figures, a services card deck, a news row, and a partner logo strip. **Use when:** The public home or landing page of a portal, ministry, authority, or platform — the page the domain root serves. Carries the main hero slider (not a sub hero), a row of headline figures that count up, a services card deck the visitor pages through, a three-across news row, and a partner logo strip. Use for home page, landing page, portal home, or main page. Copy the hero from here rather than composing it: the main hero is a swiper and needs its full navigation block.
- [Form Template](https://mazin-musleh.github.io/NDS-vanilla/templates/form-template.html): Multi-step form layout with grouped text inputs, side stepper (vertical on desktop, radial on mobile), and a flat sub-hero. **Use when:** Any multi-step form or wizard: service application, request submission, registration workflow, onboarding, or checkout. Carries the grouped input types and a progress stepper that runs vertically beside the form on desktop and as a radial dial on mobile. The stepper column is the side info arrangement, through nds-wSideInfo on the content layout.
- [Service Page Template](https://mazin-musleh.github.io/NDS-vanilla/templates/service-template.html): Government digital service with side info, breadcrumbs, and structured content layout. **Use when:** The landing page for a single government service: what it is, who is eligible, the steps, the fees, and the start-service action. The side-info column, breadcrumbs, hero tags, and the rating widget are all switched on from front matter (layout_class: nds-wSideInfo, breadcrumb, rating).
- [Contact Us Template](https://mazin-musleh.github.io/NDS-vanilla/templates/contact-us-template.html): Contact page with two-column form, country-code prefix, select, textarea, file upload, and a side info card with emergency contacts. **Use when:** A contact or enquiry page: a two-column message form with a country-code phone prefix, select, textarea, and file upload, beside a card listing phone, email, and emergency contacts. Use for contact us, feedback, support request, or get-in-touch pages. The contacts card is the side info column (nds-wSideInfo).
- [Content Template](https://mazin-musleh.github.io/NDS-vanilla/templates/content-template.html): Long-form editorial layout with article-style sections, numbered sub-sections, and a sticky on-this-page table of contents for in-page navigation. **Use when:** Any long-form editorial page: policy, terms of use, privacy notice, regulation, news article, press release, or a written guide. Carries article sections, numbered sub-sections, and a sticky on-this-page table of contents. The table of contents is the side info column (nds-wSideInfo).
- [Help & Support Template](https://mazin-musleh.github.io/NDS-vanilla/templates/help-support-template.html): Help hub with a flat sub-hero and a responsive grid of support-channel cards, each with a featured icon, description, availability, and response time. **Use when:** A support hub that routes people to help channels such as phone, email, live chat, or a ticket form. Each card carries an icon, description, availability hours, and response time.
- [About The Entity Template](https://mazin-musleh.github.io/NDS-vanilla/templates/about-entity-template.html): Entity landing hub with a flat sub-hero and a responsive grid of topic cards, each with a featured icon, title, and navigation arrow. **Use when:** Any page whose job is to route onward through a grid of icon cards. Use for a feature row or feature grid inside a larger page, and for topic hubs such as About Us, Departments, Sectors, Initiatives, Our Work, or any parent page that links to its sub-pages. Copy the card markup from here rather than composing it: each card carries its featured icon in its own header block.
- [FAQ Template](https://mazin-musleh.github.io/NDS-vanilla/templates/faq-template.html): Frequently asked questions layout with a flat sub-hero, large accordion list, and a feedback call-to-action card for routing unresolved inquiries to support. **Use when:** A frequently asked questions or knowledge-base page: a searchable and filterable accordion list, plus a still-need-help card that routes to support.
- [e-Participation Template](https://mazin-musleh.github.io/NDS-vanilla/templates/e-participation-template.html): Engagement topics hub with a sub-hero and a responsive 4-column grid of text-only navigation cards for citizen participation entry points. **Use when:** A hub of text-only navigation cards, four across, with no icons. Use for citizen participation, public consultations, surveys, polls, suggestion boxes, or any compact list of entry points where icons would add nothing.
- [Social Media Template](https://mazin-musleh.github.io/NDS-vanilla/templates/social-media-template.html): Social channels hub with a flat sub-hero and a responsive grid of platform cards, each with a featured icon, name, and navigation arrow. **Use when:** A page that lists external destinations as icon cards. Use for official social accounts, partner sites, related portals, mobile app store links, or any outbound link directory.
- [KPIs Template](https://mazin-musleh.github.io/NDS-vanilla/templates/kpis-template.html): Performance dashboard combining KPI counter tiles, pie, donut, line, and bar charts, and responsive data tables for portal and service statistics. **Use when:** A read-only reporting page: KPI counter tiles, pie, donut, line, and bar charts, and data tables. Use for performance reports, portal statistics, open-data pages, annual figures, or any analytics view. Pick the Manage Records example instead when people must edit the data.
- [Search Template](https://mazin-musleh.github.io/NDS-vanilla/templates/search-template.html): Search results layout with keyword highlighting, filter/sort dropmenus, and paginated card list. **Use when:** A search results page: the matched keyword highlighted inside each result, filter and sort dropmenus, and a paginated list of result cards.
- [404 Template](https://mazin-musleh.github.io/NDS-vanilla/templates/404-template.html): Custom error page with illustration and back-to-home action. **Use when:** An error or dead-end page: 404 not found, 500, maintenance, or access denied. A centered illustration, a message, and a back-to-home action. It is built as a hero section, not from the empty-state component, and it ships its own centered wrapper with no content layout. It is a status section with no status set, so it shows the illustration. For any other outcome page - request submitted, payment failed, access granted - keep this shape, set data-status on the section, and swap the illustration for a feedback icon in nds-section-icon. See the Status Section layout page.

## Examples

Composed pages showing NDS components working together in real government-service contexts.
- [Services List](https://mazin-musleh.github.io/NDS-vanilla/examples/services-list.html): Filterable government services catalog with search and category filters. **Use when:** A browsable catalog of items shown as cards, with keyword search, category filters, and pagination. Use for any service directory, product listing, document library, resource index, or list-all-X page. The plain content-page shape: full chrome, sub hero, no side columns.
- [Registration](https://mazin-musleh.github.io/NDS-vanilla/examples/registration.html): Sign-up form with field validation, a matching password check, and an OTP step. **Use when:** A standalone create-account or sign-up flow, with field validation, a confirm-password match check, and an OTP verification step. The page carries no topbar, header, or footer (the minimal chrome shape), so use it for any full-screen auth flow.
- [Sign In](https://mazin-musleh.github.io/NDS-vanilla/examples/sign-in.html): National single sign-on with a credentials fallback, one-time code, and account settings. **Use when:** A standalone login page: national single sign-on as the primary path, a username and password fallback, an OTP step, and a resend button with a cooldown timer. No topbar, header, or footer (the minimal chrome shape).
- [Faculty Profile](https://mazin-musleh.github.io/NDS-vanilla/examples/faculty.html): Faculty member page with profile, tabbed content, and structured academic information. **Use when:** A profile page for one person: avatar header, tabbed sections, a definition list of structured fields, and tables of related records. Sits in a card-view content layout beside a side menu, through nds-cardView and nds-wSideMenu. It is the only example whose side menu becomes a top dropdown bar on mobile, through nds-top on the aside. Use for staff bios, employee profiles, member directory detail pages, or any view-this-person screen.
- [Faculty CV](https://mazin-musleh.github.io/NDS-vanilla/examples/faculty-cv.html): Long-form academic profile with a table of contents, a career timeline, qualifications, and paginated publications. **Use when:** A profile page read top to bottom instead of through tabs, with a sticky table of contents tracking the sections as you scroll: a portrait and name in the hero, a contact menu, a card grid of key fields, a prose block, a dated career timeline built from a reversed vertical stepper so the newest entry sits on top, qualification cards, and a long list of records split into pages. Use for a CV, resume, portfolio, staff bio, work history, or any person page whose sections are too long to hide behind tabs. The table of contents is the side info column, through nds-wSideInfo on the content layout.
- [Academic Program](https://mazin-musleh.github.io/NDS-vanilla/examples/program.html): Degree program page with expandable content, curriculum, and admission information. **Use when:** A detail page for one program or offering: overview text, stat tiles, tabbed sections, expandable blocks, and detail tables. Sits in a card-view content layout beside a side menu, through nds-cardView and nds-wSideMenu. Use for courses, training programs, grant schemes, initiatives, or any about-this-thing page too long for a card.
- [Manage Records](https://mazin-musleh.github.io/NDS-vanilla/examples/manage-records.html): Records screen with create, edit and delete, filters, expandable detail rows and CSV export. **Use when:** The data-heavy admin screen, and the closest fit for any data grid, data table, CRUD screen, admin list, records management, or back-office table request, including replacements for third-party table plugins. Carries a large table with keyword search, multi-field filters (checkbox, range, date), column sorting, pagination with a per-page picker, a show/hide column picker, row selection with a live count, per-row edit and delete actions, expandable sub-rows for detail, add and edit modals, an empty-state message, and CSV export. Runs fully in the browser, so no server is needed. Runs edge-to-edge beside a side menu through nds-full-width on body, like the Console.
- [Console](https://mazin-musleh.github.io/NDS-vanilla/examples/console-demo.html): Admin console with charts, transactions, team directory, and notifications. **Use when:** The landing page of an admin area: KPI stat tiles, charts, a recent-activity table, a people directory, and alert notifications. Runs edge-to-edge beside a side menu through nds-full-width on body. Use for admin home, back-office overview, control panel, or internal tool landing screens.

## Optional

- [Live site & full documentation](https://mazin-musleh.github.io/NDS-vanilla/)
- [Source repository](https://github.com/mazin-musleh/NDS-vanilla)
- [JavaScript source (_js/)](https://github.com/mazin-musleh/NDS-vanilla/tree/main/_js)
- [SCSS source (_sass/)](https://github.com/mazin-musleh/NDS-vanilla/tree/main/_sass)
- [Full sitemap](https://mazin-musleh.github.io/NDS-vanilla/sitemap.xml)