About The Project
Why it was built, and what it covers.
The Digital Government Authority (DGA) established a unified design language for Saudi Arabia's government websites and services. The specifications published on Figma provide a clear reference; the challenge is turning that specification into maintainable, production-ready code.
The DGA's official implementation is a React and Storybook component library covering the core UI components. This project provides the design system in plain HTML, CSS, and JavaScript, together with the component library, layout system, page templates, documentation, and development environment. No frontend framework is required.
The system is also built for AI-assisted development. Every release ships NDS IQ, a versioned instruction system that gives AI coding agents a consistent way to build with NDS.
This is an independent community implementation, not affiliated with, endorsed by, or maintained by the Digital Government Authority (DGA) or the Government of Saudi Arabia.
Who It's For
Built for teams and individuals delivering, adapting, or learning government-grade web development.
Delivering DGA-aligned digital services on their existing technology stack.
Building client sites with a reusable component library and ready-to-use page templates.
Learning core HTML, CSS, and vanilla JavaScript from a readable, production-grade codebase.
Using real components, page templates, and patterns as practical material for web-development courses, bootcamps, or workshops.
The default visual identity is exclusive to Saudi Arabia government entities. It covers design tokens, colors, logos, and the digital-stamp component. Non-government projects must replace these with the adopting organization's own identity before deployment.
Compliance Ready
DGA page templates implemented as working code and ready to be adapted for deployment.
Components follow the defined design tokens, typography, spacing, and interaction patterns. The templates below cover common government service screens and can be copied, populated with project content, and adapted for deployment.
Real-World Examples
8 composed pages demonstrating NDS components working together in government service contexts.
Event Themes
Theme packs for national occasions. Each theme can be applied site-wide through a single attribute and removed to restore the default theme.
Re-skin the whole site for Saudi National Day with one script tag: the official six-slide campaign hero, identity bars under every section, and a themed footer, in both light and dark mode.
Re-skin the whole site for Saudi Founding Day with one script tag: the heritage brown palette and a configurable bilingual hero slide, in both light and dark mode.
Re-skin the whole site for the Hajj season with one script tag: a Saudi-font hero, a direction-aware backdrop, and seasonal section accents, in both light and dark mode.
Components (98)
Each with its markup, styling, and JavaScript behavior. All built from scratch.
Site-wide panel for accessibility presets, typography tuning, and visual filters
Expandable content panels with nested group support
Contextual messages for status, warnings, and notifications
Type-ahead search with filtered suggestions
Profile images, initials, and group stacks
Spacing unit for content and block components inside a section body, with an optional title
Hierarchical path showing the current page location
Interactive actions with multiple variants, sizes, and states
Versatile content containers for articles, profiles, and actions
Lightweight SVG charts: bar, line, pie, and donut
Multi-select toggles for options and preferences
Compact labels for tags, filters, and selections
Real-time clock with Hijri/Gregorian date
Formatted code blocks with syntax highlighting and copy
Dashed stand-in marking a region a real component will replace
Toggle between content sections within the same space on the screen
Privacy-compliant cookie management banner
Click-disabled countdown button for resend, retry, and rate-limited actions
One-click clipboard copy with checkmark feedback and screen reader announcement
Scroll-triggered animated counters that count up to a target value
SAR and international currency symbols appended automatically via data attribute
Styled single-choice dropdown with custom option markup and a JS API, built on dropmenu
Hijri/Gregorian calendar with dual date conversion
Structured key-value pairs in grid or list layouts
Government authority verification panel
Horizontal or vertical rule with optional centered label
Critical CSS, deferred bundles, and the inline gate every page loads in its head
Collapsible navigation lists with accordion groups
Toggle-activated overlay for actions and navigation
Rich text field that submits clean NDS markup, converting Word, Google Docs, and web pastes and inserting NDS components as blocks
Parent-adaptive placeholder for containers with no content
Show more/less toggle for long content blocks
Declarative CSV, Excel, and PDF downloads from any table, card list, or marked-up container
Decorative icon containers with shape and color options
Semantic status icons for success, error, and info
Drag-and-drop file input with preview and validation
Applied filters with search, URL sync, and remote data
Quick alignment, direction, and wrapping with custom-property overrides
FAB that pins to a viewport corner and stacks with others
Multi-column footer with light and green variants
Responsive column system with flexible breakpoints
The region at the top of the page where the top bar, digital stamp panel, and main navigation compose
Full-width page banners with slider and call-to-action
Single-purpose classes for your own markup: centering, spacing reset, direction isolation, brand text color, and notes
Visibility utilities: the hidden attribute honored everywhere and band-exact responsive hiding with data-hidden
The HugeIcons Stroke Rounded font for content plus a curated inline SVG set for components and chrome, with sizing, color, and license guidance
IPV fullscreen image preview with zoom and navigation
Inline navigation with color variants and automatic external-link detection
Spinners and skeleton placeholders for loading states
Primary navigation bar with branding, mega-menu dropdowns, utility actions, and a mobile drawer
Dashboard tile pairing a key statistic with an inline sparkline
Focused dialog overlays for confirmations and forms
Multi-option select over a native checkbox group: removable chips, JSON-populated options, staged or instant commit
Numeric field with increment and decrement controls, min/max, and step
Locale-aware thousand separators for any number on the page
Segmented one-time password fields with auto-advance
Password field with live strength rules and confirm-match checking
Page-by-page navigation for large data sets
The body structure every page shares, with the classes that switch chrome shape
Content-agnostic surface that slides in from any edge of the viewport
Identity block with avatar, name, role, and optional action row
Visual indicators for task completion and loading
Default styling for classless flowing content from editors and CMSs
Semantic quotation block with optional title and author attribution
Single-choice selection within a group
Star-based display and input for user ratings
One call that tells every live component the contents of a container changed
Fetch wrapper with a timeout, a response size cap, and errors you can branch on
Bundled JSON dataset of 132 Saudi Arabian cities with bilingual names, drop-in for autocomplete and address flows
Overflow wrapper with edge mask-fade and sticky show-more button
Page content sections with head, body, and action areas
Selected-items counter for tables, card grids, and checkbox lists, with a records-line swap while a selection is active
Native dropdown menus for choosing from a list
Social share dropmenu for X, LinkedIn, WhatsApp, and copy link
Companion column for service details, progress, and in-page navigation
Collapsible nested sidebar navigation
Numeric range input with single-thumb and dual-thumb modes for picking a value or a min–max span
DOM-reorder engine for lists, grids, and tables with type auto-detect and URL sync
Whole-page or inline outcome message with a status icon, a title, and one action
Sequential step indicators for multi-stage workflows
Touch-enabled carousel for images and content slides
Binary on/off toggles for settings and preferences
Data grids with sorting, pagination, and expandable rows
Switchable content panels with horizontal tab navigation
Free-text tags committed as removable chips while typing, posted natively as an array
Small labels for categorization and metadata
Single-line fields with labels, icons, and validation
Resizable multi-line text fields
Light and dark mode, plus brand theming: generate a full palette from OKLCH seed colours, or override the design tokens with a stylesheet theme
Auto-populated in-page table of contents with active-section tracking
Every CSS custom property in the system: palette, primitive scales, semantic meanings, and component dials to reference and override
Controls bar above a table, list, or grid: result counts and applied filters lead, export and actions trail
Click-activated balloon for contextual help next to a term or field
Government branding bar with date, weather, and dark mode toggle
Line-clamped overflow with expand/collapse toggle
Satisfaction surveys and inline rating forms
Voice-to-text button that dictates into a text field, with Arabic/English auto-detection
Live weather display from GPS coordinates
Architecture & Performance
Built with a performance-first and compatibility approach.
No Bootstrap, Tailwind, jQuery, or framework runtime. The output is plain HTML, CSS, and JavaScript and can be integrated into existing stacks without introducing a framework dependency.
A single DOM sweep detects the components present on a page and initializes them in priority tiers: critical components first, followed by the rest during idle time. Deferred and page-specific bundles are loaded only when their components are present, limiting each page to the JavaScript it actually uses.
Built with CSS Logical Properties from the start. Margins, padding, borders, and positioning adapt to direction without a separate RTL stylesheet or directional overrides. Switch between RTL and LTR with a single HTML attribute.
Palette, primitive, semantic, and component tokens are defined as CSS custom properties. Components expose public properties for customization while keeping internal implementation details private.
Light and dark modes are built in, with support for full re-branding. Generate a palette from a single OKLCH seed color, select a predefined theme, or load a stylesheet theme. Theme selection is controlled through a single HTML attribute and requires no rebuild.
Critical styles load immediately, while non-critical styles are deferred and loaded asynchronously without blocking rendering. The build separates critical and non-critical CSS.
First paint is divided into five render-safe stages: inline critical skeleton → critical stylesheet → main stylesheet → main JavaScript → icons and font. Each stage either renders correctly or remains hidden, preventing unstyled flashes; icons load last to stay outside the LCP window.
The full library is ~133 KB gzipped, but it is not loaded as a single bundle. A lean ~41 KB core loads on every page, while late-safe and page-specific components are loaded only when their markup is present. A typical page therefore executes only a fraction of the library.
100% Google PageSpeed score, with LCP, CLS, and INP passing in the measured test. Performance is tested across desktop and mobile conditions, including fast and limited connections.
GPU-accelerated animations and scheduled rendering keep transitions responsive, including on lower-end devices. Off-screen elements are deferred until needed.
Development Environment
Everything needed to build, modify, and extend the system.
The project uses Jekyll, a static site generator supported by GitHub Pages. It compiles templates, stylesheets, and data files into static HTML with no external toolchain.
NDS is designed to work with AI coding agents, with NDS IQ providing the instructions and Get Started guiding the setup and workflow.
Sass uses a modular file structure with one stylesheet per component. Shared variables, mixins, and design tokens are available across the system. Jekyll compiles and minifies the styles into the final CSS output.
Vanilla JavaScript uses one source file per component and is controlled by the component loader. Only components present on a page initialize. A Ruby processor bundles and minifies with Terser into tiered outputs: a lean core plus deferred and page-specific bundles loaded on demand.
Jekyll's built-in template engine supports layouts, includes, partials, loops, conditions, and data binding. Pages are composed from reusable blocks rather than duplicated markup.
YAML files provide structured project data. Menus, navigation, hero content, and site configuration are stored as data and supplied to templates at build time.
Custom Ruby scripts extend Jekyll's build process for tasks such as JavaScript bundling, HTML compression, and base URL resolution. Each plugin is project-specific and editable.
Get Started
Everything needed to adopt NDS: download the template, install the agent instructions, build the UI page by page, and stay current with upgrades.