About The Project
Why it was built, and what it covers.
Credit to the Digital Government Authority (DGA) for its outstanding work in unifying Saudi Arabia's government websites and services under a single, coherent design language. The specifications published on Figma are clear and comprehensive; however, translating them into working code remains a challenge for most teams.
The DGA's official implementation is a React and Storybook component library that covers the core UI components. This project provides the same design system in plain HTML, CSS, and JavaScript, and includes all components, a layout system, page templates, documentation, and a complete development environment. No framework is required.
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 the people delivering, customizing, and learning government-grade web development.
Delivering DGA-compliant digital services on whatever stack they already use.
Shipping client sites quickly with a polished component library and page templates out of the box.
Learning core HTML, CSS, and vanilla JavaScript from a readable, production-grade codebase.
Using real components, page templates, and patterns as study cases for web-development courses, bootcamps, or workshops.
The default visual identity (design tokens, colors, logos, and the digital-stamp component) is exclusive to Saudi Arabia government entities. Any non-government use must replace these with the adopting organization's own identity before deploying.
Compliance Ready
Official DGA page templates, converted into live, working code and ready for deployment.
Every component adheres to the official design tokens, typography, spacing, and interaction patterns. The templates below cover the most common government service screens, ready to copy, populate with your content, and publish.
Real-World Examples
5 composed pages showing NDS components working together in real government service contexts.
Event Themes
Seasonal theme packs for national occasions. Each one re-skins the whole site from a single drop-in tag, and removing it restores the default when the event ends.
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 (91)
Each with 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
Titled content grouping primitive for sub-sections inside a section body
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
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
Top bar and primary navigation shell with mega menus and mobile drawer
Full-width page banners with slider and call-to-action
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
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
Page-by-page navigation for large data sets
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
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
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 that works in any environment. No conflicts with existing scripts or stylesheets. Drop it into any project regardless of tech stack.
A single DOM sweep detects which components a page uses and initializes them in priority tiers: critical ones first to unblock first paint, then the rest on idle. Deferred and page-specific bundles are fetched only when their components are present, so each page downloads and runs only the JavaScript it actually uses.
Built with CSS Logical Properties from the start. Margins, paddings, borders, and positions adapt automatically. No separate RTL stylesheet. No overrides. Switch direction with a single HTML attribute.
Palette, primitives, semantic, and component tokens, all defined as CSS custom properties. Each component exposes public properties for customization while keeping internal styles private, no overrides needed.
Light and dark mode out of the box, plus full re-branding: generate an entire palette from a single OKLCH seed color, pick a predefined theme, or drop in a stylesheet theme. All driven from one HTML attribute, with no rebuild.
Critical styles load immediately for instant render. The rest is deferred and loads asynchronously without blocking the page. Styles are split between critical and non-critical at the build level.
First paint is layered across five render-safe stages — inline critical skeleton → critical stylesheet → main stylesheet → main JavaScript → icons & font. Each stage paints correctly or holds hidden, never a flash of unstyled content, and icons load last to stay clear of the LCP window.
The full library is ~93 KB gzipped, but it never ships at once. A lean ~35 KB core loads on every page, while late-safe and page-specific components live in separate bundles the loader fetches only when their markup is present. A typical page runs a fraction of the library.
100% Google PageSpeed score. LCP, CLS, and INP all pass. Measured and optimized for real-world conditions. Tested across desktop and mobile on both fast and limited connections.
GPU-accelerated animations with optimized scheduling deliver smooth transitions even on lower-end devices, with a native application feel. Off-screen elements are not rendered until needed.
Development Environment
Everything needed to build, modify, and extend the system.
The project is built on Jekyll, a static site generator natively supported by GitHub Pages. It compiles templates, stylesheets, and data files into static HTML with no external toolchain.
Sass with a modular file structure. Each component has its own stylesheet. Variables, mixins, and design tokens are shared across all files. Jekyll compiles and minifies everything into a single CSS output.
Vanilla JavaScript with one file per component, controlled by a smart loader. Only active components initialize on each page. 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 with no duplicated markup.
YAML files act as a flat-file database for the project. Menus, navigation, hero content, and site configuration are stored as structured data and fed into templates at build time.
Custom Ruby scripts that extend Jekyll's build process. Handle JS bundling, HTML compression, baseurl resolution, and more. Each plugin is project-specific and fully editable.
Ships agent instructions in the cross-tool AGENTS.md format, picked up by Claude Code, Cursor, Codex, and other AI assistants, with custom skills for documentation, content creation, code review, and component auditing. The codebase is structured for effective AI-assisted development.
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.