docs: Add USWDS theming guide

docs/development/THEMING_GUIDE.md

@@ -0,0 +1,181 @@
+# VEDA UI theming guide
+
+## Overview
+
+VEDA UI library uses the [U.S. Web Design System (USWDS)](https://designsystem.digital.gov/) as its foundation for styling and theming. This guide explains how to set up and customize styles in your application when using VEDA UI components.
+
+## Setup requirements
+
+To use VEDA UI components with proper styling, your application needs to:
+
+1. Install the required dependencies:
+
+```bash
+# VEDA UI uses @uswds/uswds@^3.8.1 as a peer dependency
+# Install the same or compatible version to avoid styling issues
+npm install @uswds/uswds@^3.8.1 sass
+# or
+yarn add @uswds/uswds@^3.8.1 sass
+```
+> **Note:** Version compatibility is important. VEDA UI currently uses USWDS v3.8.1 as a peer dependency. Using a significantly different version might cause styling inconsistencies.
+
+2. Configure your build system to handle SASS files
+3. Create the necessary theme configuration files
+
+## Theme configuration
+
+### USWDS theming system
+
+USWDS uses a token-based design system that provides a good foundation for consistent styling. The [USWDS theme documentation](https://designsystem.digital.gov/documentation/settings/) provides detailed information about all tokens and settings available for customizing your application's visual design.
+
+### Style import order
+
+The order of importing styles is important so that proper styles cascading can be applied:
+
+1. USWDS theme settings
+2. VEDA UI styles
+3. Custom application styles
+
+```scss
+// 1. Theme settings
+// This imports all theme-related settings which can be configured in _uswds-theme.scss
+// Variables like theme-image-path, theme-font-path, color tokens etc.
+@forward 'uswds-theme';
+
+// 2. USWDS core styles
+// Imports all USWDS components and styles
+// For smaller bundle size, you can optionally import specific packages instead:
+// @use '@uswds/uswds/packages/usa-button';
+// @use '@uswds/uswds/packages/usa-modal';
+// etc.
+@forward 'uswds';
+
+// 3. USWDS core utilities
+// Provides all USWDS functions, mixins, and tokens
+// The 'as *' syntax allows direct usage without namespacing
+// e.g. color(gray-90) instead of uswds.color(gray-90)
+@use 'uswds-core' as *;
+
+// Note: For custom styles that override VEDA UI and/or USWDS,
+// create a separate custom.scss file and import it last in your application
+// Import order in your app:
+// 1. import '@developmentseed/veda-ui/lib/main.css';
+// 2. import './styles/index.scss';
+// 3. import './styles/custom.scss';
+```
+
+## Example implementation
+
+Below is an example of implementing VEDA UI theming in a Next.js application. While your specific setup may vary based on your framework and build tools, the core concepts remain the same.
+
+### Next.js example
+
+1. Configure SASS options in `next.config.js`:
+
+```js
+module.exports = {
+ sassOptions: {
+   includePaths: [
+     'node_modules/@uswds/uswds',
+     'node_modules/@uswds/uswds/dist',
+     'node_modules/@uswds/uswds/packages',
+   ]
+ }
+};
+```
+
+2. Create theme configuration in `styles/_uswds-theme.scss`:
+
+```scss
+// This section showcases basic USWDS configuration examples
+// For all available settings and detailed documentation, visit:
+// https://designsystem.digital.gov/documentation/settings
+@use 'uswds-core' with (
+ // Asset path configurations
+ $theme-image-path: '/img',
+ $theme-font-path: '/fonts',
+
+ // General settings
+ $theme-show-notifications: false,
+ $utilities-use-important: true,
+
+ // Typography settings
+ $theme-font-weight-semibold: '600',
+ $theme-type-scale-md: 8,
+
+ // Color settings
+ $theme-color-base-darkest: 'gray-cool-80',
+ $theme-color-base-ink: 'gray-cool-90',
+ $theme-color-primary: 'red-50',
+ $theme-color-secondary: 'yellow-30'
+);
+```
+
+3. Create main SCSS entry file in `styles/index.scss`:
+
+```scss
+@forward 'uswds-theme';
+@forward 'uswds';
+@use 'uswds-core' as *;
+```
+
+4. Import the styles in the root of your application:
+
+```typescript
+import './styles/index.scss';
+import '@developmentseed/veda-ui/lib/main.css';
+// Any other custom styles
+import './styles/custom.scss';
+```
+
+## Best practices
+
+1. Use USWDS design tokens:
+
+```scss
+// Good
+.custom-element {
+ color: color(gray-90);
+ margin: units(2);
+}
+
+// Avoid hard coding values
+.custom-element {
+ color: #e41d3d;
+ margin: 16px;
+}
+```
+
+2. Make use of USWDS mixins and functions:
+
+```scss
+.custom-component {
+ @include u-padding-x(2);
+ @include u-margin-y(1);
+ @include typeset('sans', 'sm');
+}
+```
+
+3. Follow [USWDS custom theme guidelines](https://designsystem.digital.gov/documentation/settings/) to keep the theming consistent.
+
+## Troubleshooting
+
+Common issues and solutions:
+
+1. SASS module resolution issues:
+  - Make sure that USWDS paths are correctly configured in your build system
+
+2. Style precedence problems:
+  - Make sure the import order is correct in your main SCSS file
+  - Check specificity of custom styles
+
+3. Missing USWDS assets, such as the icons?
+  - Confirm theme-image-path and theme-font-path are correctly set
+
+## Additional resources
+
+- [USWDS design tokens documentation](https://designsystem.digital.gov/design-tokens/)
+- [USWDS settings and theme configuration](https://designsystem.digital.gov/documentation/settings/)
+- [USWDS utilities](https://designsystem.digital.gov/utilities/)
+- [USWDS layout grid](https://designsystem.digital.gov/utilities/layout-grid/)
+- [SASS guidelines](https://sass-lang.com/guidelines/)