Theming
Global PHP configuration
The Config class provides static methods to set and get several options to be made available to components at runtime, such as global background colour and default icon prefix. In general usage, these can be set directly.
In WordPress, themes (other than Comet Canvas) don't generally have direct access to the Config class, unless you have installed the Comet Components core library yourself. Comet Canvas provides filters so that child themes can easily override the defaults from functions.php.
Global background colour
Important
By setting the global background colour in the Comet config, you are making it available to all components at runtime, allowing them to use this context to refine styling.
Simply adding the colour to the body tag manually will not have the full effect, because the PHP component classes will not be aware of it when constructing component instances.
Warning
The string must be a colour name (not a hex code) matching the value of a ThemeColor.
General usage
You can set a global background colour for your site using this line of code in an appropriate location.
For a "vanilla" project this could be as simple as calling it at the top of the page:
Config::getInstance()->set_global_background('dark');
You then simply need to add the data-global-background attribute to the body tag:
<?php
$globalBackground = Config::getInstance()->get_global_background();
?>
<body data-global-background="<?php echo $globalBackground; ?>">
In WordPress
Comet Canvas provides a filter to override the default (white) in your child theme's functions.php like so:
add_filter('comet_canvas_global_background', fn() => 'dark', 20);
Default icon prefix
Components that render icons do so using the Icon trait, which uses two attributes passed from the component $attributes: icon and an optional iconPrefix. These values are usually passed to a HTML <i> element as class names in the component's Blade template.
The default iconPrefix is Font Awesome's fa-solid, but this can be overridden both at the global configuration level and at component level. For example if you want to use fa-light by default, but then fa-solid for a specific component, you can do so by setting fa-light in the global configuration and then passing fa-solid in the special component's $attributes.
General usage
You can set a default icon prefix for your site using this line of code in an appropriate location:
Config::getInstance()->set_icon_prefix('fa-duotone fa-solid');
In WordPress
Comet Canvas provides a filter to override the default icon prefix in your child theme's functions.php like so:
add_filter('comet_canvas_default_icon_prefix', fn() => 'fa-light', 20);
Global CSS configuration
Many design tokens are set as CSS variables in Comet's stylesheets, allowing you to easily override them without any special tooling. Sass can be useful for calculating values (such as for the readable colour variables) but it is not essential. You can hit the ground running with a simple vanilla stylesheet that sets the variables you want to change. The full list of tokens can be found in the:root selector in global.css and in the list below.
Important
For WordPress usage, some tokens should be set in your theme's tokens.css file so that they take effect in the editor as well.
General usage
Set colours, fonts, spacing, font weights, and container widths by overriding Comet's CSS variables in your own style.css file. For example:
- Set fonts with the
--font-family-bodyand--font-family-accentvariables - Set colours with the
--color-primary,--color-secondary, etc. variables (unless you are using WordPress - see below).
:::
In WordPress
- Set colours and gradients in your theme's
tokens.cssfile. WordPress will automatically pick up on these for use in the editor, overriding the Comet default ones. - Set fonts and other CSS variables as per the general usage instructions above.
:::
Default design tokens (CSS variables)
Tips
The working proposal for CSS Color Module Level 6 includes bringing colour contrast functions to vanilla CSS. When this is finalised and hits widespread browser support, the HSL and "readable colour" Sass calculations will likely be replaced with these, removing the need to calculate them in SCSS or manually.
Colours
| Colour variable name | Default value | Readable* |
|---|---|---|
--color-primary | #845ec2 | white |
--color-secondary | #00c9a7 | white |
--color-accent | #ba3caf | white |
--color-info | #00d2fc | white |
--color-warning | #f9c971 | black |
--color-success | #00c9a7 | white |
--color-error | #d23e3e | white |
--color-light | #f0f0f2 | black |
--color-dark | #4b4453 | white |
*Corresponding "readable" variable e.g., --readable-color-primary.
See _variables.scss and global.scss for how the readable colours are calculated for the default colours using Sass. You can copy this into your own SCSS to calculate the overrides for your own colours.
Typography
| Variable name | Default value |
|---|---|
--font-family-body | sans-serif |
--font-family-accent | sans-serif |
--font-size-sm | 0.875rem |
--font-weight-light | 300 |
--font-weight-regular | 400 |
--font-weight-semibold | 600 |
--font-weight-bold | 700 |
Spacing
The default spacing values use an augmented fourth scale from small upwards.
| Variable name | Default value | |
|---|---|---|
--spacing-xxs | 0.25rem | |
--spacing-xs | 0.5rem | |
--spacing-sm | 0.707rem | |
--spacing-md | 1rem | |
--spacing-lg | 1.414rem | |
--spacing-xl | 2rem | |
--spacing-xxl | 2.827rem |
Container widths
| Variable name | Default value |
|---|---|
--width-wide | 1440px |
--width-contained | 1100px |
--width-narrow | 960px |
--width-small | 600px |
Miscellaneous
| Variable name | Default value |
|---|---|
--button-border-radius | 0 |
Adding animation
Warning
// TODO examples of Animate-Into-View, Hover.css, etc