feat: add full Zonemaster stack with Docker and Spanish UI
- Clone all 5 Zonemaster component repos (LDNS, Engine, CLI, Backend, GUI) - Dockerfile.backend: 8-stage multi-stage build LDNS→Engine→CLI→Backend - Dockerfile.gui: Astro static build served via nginx - docker-compose.yml: backend (internal) + frontend (port 5353) - nginx.conf: root redirects to /es/, /api/ proxied to backend - zonemaster-gui/config.ts: defaultLanguage set to 'es' (Spanish) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,169 @@
|
||||
# Configuring Zonemaster-GUI using Theming
|
||||
|
||||
## Background
|
||||
|
||||
The Zonemaster-GUI is built to be cloned and customized. You have full control
|
||||
over the styling and layout. That said, to avoid troubles when syncing with
|
||||
the original repository, we recommend following a few simple guidelines:
|
||||
|
||||
- Start by customizing the **theme variables** — this is enough for most use cases.
|
||||
- If that's not enough, apply **custom CSS** targeting specific elements.
|
||||
- For large framework changes, **create a new theme** and update `tsconfig.json`.
|
||||
- For interactive components, **keep changes minimal** to avoid breaking functionality.
|
||||
- Use **headless mode** for major customizations or when building your own GUI.
|
||||
|
||||
## Related documents
|
||||
|
||||
For how to use `tsconfig.json` in connection to theming, see
|
||||
[Advanced build-time configuring Zonemaster-GUI using "tsconfig.json"]. Theming
|
||||
requires rebuilding Zonemaster-GUI, see
|
||||
[Build a custom Zonemaster-GUI installation package].
|
||||
|
||||
## Basic customization
|
||||
|
||||
The Zonemaster-GUI is built around a global theme based on CSS variables
|
||||
(`./src/themes/default/styles/theme.css`). The easiest way to make your own theme
|
||||
is to override theme variables in the `./src/themes/default/styles/custom.css` file.
|
||||
You can tweak colors, fonts, spacing, and more. You'll get surprisingly far by
|
||||
just updating the theme variables. All class names are prefixed with `zm-` to
|
||||
avoid conflicts with other styles. This makes it easy to apply custom CSS on top
|
||||
of the theme to target specific elements.
|
||||
|
||||
### Available theme variables
|
||||
|
||||
The theme includes variables for:
|
||||
- **Font sizes and families**: `--font-xxs` through
|
||||
`--font-supersize`, `--font-body-family`, etc.
|
||||
- **Spacing**: `--spacing-xxs` through `--spacing-xxl`
|
||||
- **Colors**: Various color palettes including main, secondary, black, danger,
|
||||
success, info, warning, and error
|
||||
- **GUI elements**: Background, text, borders, etc.
|
||||
- **Buttons**: Size, color, padding
|
||||
- **Layout**: Width, gaps, header height
|
||||
- **Breakpoints**: For responsive design
|
||||
|
||||
### Example customization
|
||||
|
||||
Here's a simple example of customizing the main color and font in `custom.css`:
|
||||
|
||||
```css
|
||||
:root {
|
||||
/* Change the primary color */
|
||||
--color-palette-main-50: #4285f4;
|
||||
--color-palette-main-70: #1a73e8;
|
||||
|
||||
/* Change the font */
|
||||
--font-body-family: 'Roboto', sans-serif;
|
||||
}
|
||||
```
|
||||
|
||||
### CSS loading order
|
||||
|
||||
The CSS files are loaded in the following order (defined in `styles.css`):
|
||||
1. theme.css (base theme variables)
|
||||
2. foundation.css and other core styles
|
||||
3. Component-specific CSS files
|
||||
4. custom.css (your customizations)
|
||||
|
||||
This ensures that your custom styles will override the default styles.
|
||||
|
||||
## Modifying structure and layout
|
||||
|
||||
There are two layers of the GUI.
|
||||
|
||||
### Framework
|
||||
|
||||
The framework is the foundation of the GUI and is built with [Astro]. These
|
||||
files are located under `./src/themes/default`. ' The starting point for these
|
||||
imports are pages. Pages are simple: they consist of a single component wrapped
|
||||
inside a layout. *We suggest not modifying the page files*. Instead, create your
|
||||
own theme, for example `./src/themes/my-theme`. You can still reuse components
|
||||
from the original theme in your new theme and mix and match the imports from your
|
||||
custom theme.
|
||||
|
||||
Then update tsconfig.json:
|
||||
|
||||
```diff
|
||||
{
|
||||
"extends": "astro/tsconfigs/strict",
|
||||
"include": [".astro/types.d.ts", "**/*"],
|
||||
"exclude": ["dist"],
|
||||
"compilerOptions": {
|
||||
"baseUrl": ".",
|
||||
"paths": {
|
||||
"@/*": ["./src/*"],
|
||||
- "@theme/*": ["./src/themes/default/*"]
|
||||
+ "@theme/*": ["./src/themes/my-theme/*"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Interactive components
|
||||
|
||||
All interactive components are built with [Svelte]. These files are located under
|
||||
`./src/lib/components`. These are referenced from Astro components. Although care
|
||||
was taken to make the components as self-contained as possible, some
|
||||
components may depend on others. In most cases you won't need to modify these
|
||||
files. A better approach is to modify the CSS.
|
||||
|
||||
If you absolutely need to modify these, the suggested method is to create new
|
||||
components in `./src/lib/components/my-theme` and reference them from the
|
||||
Astro components. These interactive components contain important functionality
|
||||
that needs to be carefully considered when modifying.
|
||||
|
||||
You might be better off creating a new component from scratch and integrate it
|
||||
with the RPCAPI yourself.
|
||||
|
||||
## Headless mode
|
||||
|
||||
For major customizations or when you need complete control over the GUI, you can
|
||||
use the "headless mode" approach. This involves using the Zonemaster API client
|
||||
directly without the GUI components.
|
||||
|
||||
For detailed information about headless mode, please refer to the [UI.md]
|
||||
documentation.
|
||||
|
||||
## Testing and troubleshooting
|
||||
|
||||
### Testing your theme changes
|
||||
|
||||
When making theme changes, it's important to test them across different pages and
|
||||
components to ensure consistency. Here are some tips:
|
||||
|
||||
1. **Test on different screen sizes**: Use your browser's developer tools to test
|
||||
responsive behavior.
|
||||
2. **Check all interactive states**: Verify hover, focus, active, and disabled
|
||||
states for interactive elements.
|
||||
3. **Test with different content**: Make sure your theme works well with both
|
||||
short and long content.
|
||||
4. **Verify accessibility**: Ensure sufficient color contrast and that focus
|
||||
states are visible.
|
||||
|
||||
### Common issues and solutions
|
||||
|
||||
- **Changes not appearing**: Make sure your `custom.css` file is being loaded.
|
||||
Check the browser's developer tools to verify.
|
||||
- **Specificity issues**: If your styles aren't overriding the defaults, you
|
||||
might need to increase specificity or use `!important` (sparingly).
|
||||
- **Responsive issues**: Check that your customizations work well at all
|
||||
breakpoints.
|
||||
- **Component styling conflicts**: If styling a specific component, target the
|
||||
component's class directly rather than modifying global variables.
|
||||
|
||||
### Development workflow
|
||||
|
||||
For a smoother development experience:
|
||||
1. Start the development server with `npm run dev`
|
||||
2. Make changes to your `custom.css` file
|
||||
3. The changes will be applied immediately thanks to hot module reloading
|
||||
4. Use browser developer tools to inspect elements and test different values
|
||||
|
||||
|
||||
[Advanced build-time configuring Zonemaster-GUI using "tsconfig.json"]: configuring-using-tsconfig-json.md
|
||||
[Build a custom Zonemaster-GUI installation package]: building-custom-gui.md
|
||||
[Astro]: https://astro.build/
|
||||
[Configuration of GUI]: https://doc.zonemaster.net/latest/configuration/gui/README.html
|
||||
[Svelte]: https://svelte.dev/
|
||||
[UI.md]: https://github.com/zonemaster/zonemaster-gui/blob/master/docs/UI.md#headless-mode
|
||||
|
||||
Reference in New Issue
Block a user