Theme Creation Guide¶

This guide covers everything you need to know about creating custom themes for BetterSEQTA+.

Table of Contents¶

Overview
Theme Structure
CSS Variables
CSS Selectors & Classes
Custom Images
Theme Settings
Best Practices
Examples

Overview¶

Themes in BetterSEQTA+ allow you to completely customize the appearance of SEQTA Learn. A theme consists of:

Custom CSS: CSS rules that override default styles
Custom Images: Images that can be referenced via CSS variables
Theme Metadata: Name, description, default color, etc.
Theme Settings: Options like forcing dark/light mode

Themes are applied by injecting CSS into the SEQTA page and setting CSS custom properties (variables) on the document root.

CSS Variables¶

BetterSEQTA+ provides a comprehensive set of CSS variables that you can use in your themes. These variables automatically adapt to light/dark mode and user preferences.

Core Background Variables¶

Variable	Light Mode	Dark Mode	Description
`--background-primary`	`#ffffff`	`#232323`	Main background color
`--background-secondary`	`#e5e7eb`	`#1a1a1a`	Secondary background color
`--theme-primary`	`#ffffff`	`#232323`	Primary theme color (same as background-primary)
`--theme-secondary`	`#e5e7eb`	`#1a1a1a`	Secondary theme color (same as background-secondary)
`--text-primary`	`black`	`white`	Primary text color
`--text-color`	`black`	`white`	Text color (alias for text-primary)

BetterSEQTA+ Specific Variables¶

Variable	Description	Notes
`--better-main`	User's selected accent color	Dynamically set based on color picker
`--better-sub`	Dark navy color	Always `#161616`
`--better-pale`	Lightened version of accent color	Only available in light mode
`--better-light`	Lighter version of accent color	Calculated based on brightness
`--better-alert-highlight`	Alert/highlight color	`#c61851`
`--betterseqta-logo`	Logo URL	Changes based on dark/light mode
`--auto-background`	Auto background color	Falls back to `--better-pale` or `--background-secondary`
`--navy`	Navy color	`#1a1a1a`
`--theme-fg-parts`	Theme foreground parts	`white`

Subject/Item Color Variables¶

Variable	Description
`--item-colour`	Subject/item color
`--colour`	Generic color variable
`--person-colour`	Person/avatar color

Transparency Effects¶

When transparency effects are enabled, background variables become semi-transparent:

Variable	Light Mode (Transparent)	Dark Mode (Transparent)
`--background-primary`	`rgba(255, 255, 255, 0.6)`	`rgba(35, 35, 35, 0.6)`
`--background-secondary`	`rgba(229, 231, 235, 0.6)`	`rgba(26, 26, 26, 0.6)`

Using CSS Variables¶

You can use these variables in your custom CSS:

/* Example: Style a custom element */
.my-custom-element {
  background: var(--background-primary);
  color: var(--text-primary);
  border: 1px solid var(--better-main);
}

/* Example: Create a gradient */
.gradient-box {
  background: linear-gradient(
    to bottom,
    var(--better-main),
    var(--background-secondary)
  );
}

CSS Selectors & Classes¶

BetterSEQTA+ uses specific CSS selectors and classes that you can target in your themes. Here are the most important ones:

Main Layout Elements¶

Selector	Description
`#container`	Main container element
`#content`	Content area
`#main`	Main content wrapper
`#title`	Top title bar
`#menu`	Sidebar menu

Dark Mode¶

The dark class is added to html when dark mode is active:

/* Target dark mode specifically */
html.dark #main {
  background: var(--background-primary);
}

/* Target light mode */
html:not(.dark) #main {
  background: var(--background-primary);
}

Transparency Effects¶

When transparency effects are enabled, the transparencyEffects class is added to html:

html.transparencyEffects .notice {
  backdrop-filter: blur(80px);
}

Common SEQTA Classes¶

Class/Selector	Description
`.notice`	Notice cards
`.day`	Day containers in timetable
`.dashboard`	Dashboard sections
`.dashlet`	Dashboard widgets
`.document`	Document elements
`.quickbar`	Quick action bar
`.calendar`	Calendar elements
`.message`	Message elements
`.thread`	Forum threads
`.shortcut`	Shortcut buttons
`.upcoming-assessment`	Upcoming assessments
`.entry.class`	Timetable entries

BetterSEQTA+ Specific Classes¶

Class	Description
`.addedButton`	BetterSEQTA+ added buttons
`.tooltip`	Tooltip elements
`.notice-unified-content`	Unified notice content
`.home-container`	Home page container
`.timetable-container`	Timetable container
`.notices-container`	Notices container

Attribute Selectors¶

SEQTA uses data attributes that you can target:

/* Target specific data types */
[data-type="student"] .header {
  color: var(--text-primary);
}

/* Target specific labels */
[data-label="inbox"] {
  /* Styles */
}

CSS Modules¶

SEQTA uses CSS modules with hashed class names. You can target them using attribute selectors:

/* Target CSS module classes */
[class*="MessageList__MessageList___"] {
  background: var(--background-primary);
}

[class*="BasicPanel__BasicPanel___"] {
  border-radius: 16px;
}

Custom Images¶

Themes can include custom images that are made available as CSS variables.

Adding Images¶

Upload an image in the theme creator
Set a CSS variable name (e.g., custom-background)
The image will be available as var(--custom-background)

Using Image Variables¶

/* Use as background */
.my-element {
  background-image: var(--custom-background);
  background-size: cover;
  background-position: center;
}

/* Use in content */
.my-icon::before {
  content: '';
  background-image: var(--custom-icon);
  width: 24px;
  height: 24px;
}

Image Variable Format¶

Images are stored as url() values:

/* The variable contains: url(blob:...) */
--custom-background: url(blob:chrome-extension://...);

Theme Settings¶

Force Dark/Light Mode¶

You can force a theme to always use dark or light mode:

forceDark: true   // Force dark mode
forceDark: false  // Force light mode
forceDark: undefined  // Use user's preference (default)

When forceDark is set, users cannot toggle dark/light mode while the theme is active.

Default Color¶

Set a default accent color for your theme:

defaultColour: "rgba(0, 123, 255, 1)"  // Blue
defaultColour: "#ff6b6b"                // Red (hex format)

Allow Color Changes¶

Control whether users can change the accent color:

CanChangeColour: true   // Users can change color
CanChangeColour: false  // Color is locked

Best Practices¶

1. Use CSS Variables¶

Always use CSS variables instead of hardcoded colors:

/* Good */
.my-element {
  background: var(--background-primary);
  color: var(--text-primary);
}

/* Bad */
.my-element {
  background: #ffffff;
  color: #000000;
}

2. Support Both Light and Dark Modes¶

Unless your theme forces a specific mode, ensure it works in both:

/* Use variables that adapt automatically */
.my-element {
  background: var(--background-primary);
  color: var(--text-primary);
}

/* Or explicitly handle both modes */
html.dark .my-element {
  background: #1a1a1a;
}

html:not(.dark) .my-element {
  background: #ffffff;
}

3. Use !important Sparingly¶

Only use !important when necessary to override SEQTA's default styles:

/* Good - necessary override */
#title {
  background: var(--background-primary) !important;
}

/* Bad - unnecessary */
.my-element {
  color: var(--text-primary) !important;
}

4. Test Responsive Design¶

SEQTA is responsive. Test your theme at different screen sizes:

/* Example: Mobile-specific styles */
@media (max-width: 900px) {
  #menu {
    transform: translate(-270px);
  }
}

5. Use Semantic Selectors¶

Prefer semantic selectors over fragile ones:

/* Good - stable selector */
#main > .dashboard > section {
  border-radius: 16px;
}

/* Caution - CSS module classes may change */
[class*="Dashboard__Dashboard___"] {
  border-radius: 16px;
}

6. Optimize Images¶

Keep image file sizes reasonable:

Use appropriate formats (PNG for transparency, JPG for photos)
Compress images before uploading
Consider using CSS for simple graphics instead of images

7. Document Your Theme¶

Include comments in your CSS explaining complex styles:

/* 
 * Custom gradient background for dashboard
 * Uses the user's accent color for a cohesive look
 */
#main > .dashboard {
  background: linear-gradient(
    135deg,
    var(--better-main),
    var(--background-secondary)
  );
}

Examples¶

Example 1: Simple Color Theme¶

/* Change accent color throughout */
:root {
  --better-main: #ff6b6b;
}

/* Style the menu */
#menu {
  background: var(--background-primary);
  border-right: 3px solid var(--better-main);
}

/* Style buttons */
.uiButton {
  background: var(--better-main);
  color: var(--text-color);
  border-radius: 8px;
}

Example 2: Custom Background Image¶

/* Use a custom background image */
body {
  background-image: var(--custom-background);
  background-size: cover;
  background-attachment: fixed;
}

/* Add overlay for readability */
#main::before {
  content: '';
  position: fixed;
  top: 0;
  left: 0;
  right: 0;
  bottom: 0;
  background: rgba(0, 0, 0, 0.3);
  z-index: -1;
}

Example 3: Rounded Corners Theme¶

/* Make everything more rounded */
#main > .dashboard > section,
.dashlet,
.notice,
.document {
  border-radius: 20px !important;
}

/* Round buttons */
.uiButton {
  border-radius: 25px !important;
}

Example 4: Minimal Theme¶

/* Remove shadows and borders */
#main > .dashboard > section,
.dashlet,
.notice {
  box-shadow: none !important;
  border: 1px solid var(--background-secondary) !important;
}

/* Simplify colors */
#menu {
  background: var(--background-primary) !important;
}

/* Remove gradients */
.day {
  background: var(--background-primary) !important;
}

Example 5: High Contrast Theme¶

/* Increase contrast */
:root {
  --background-primary: #000000;
  --background-secondary: #1a1a1a;
  --text-primary: #ffffff;
}

html:not(.dark) {
  --background-primary: #ffffff;
  --background-secondary: #f0f0f0;
  --text-primary: #000000;
}

/* Add borders for clarity */
.dashlet,
.notice,
.document {
  border: 2px solid var(--better-main) !important;
}

Advanced Techniques¶

CSS Custom Properties Override¶

You can override CSS variables in your theme:

/* Override a variable */
:root {
  --better-main: #your-color;
}

/* Override conditionally */
html.dark {
  --background-primary: #your-dark-color;
}

Animations¶

Add smooth transitions:

/* Smooth color transitions */
#menu li {
  transition: background-color 0.3s ease;
}

/* Hover effects */
.dashlet:hover {
  transform: translateY(-2px);
  box-shadow: 0 4px 12px rgba(0, 0, 0, 0.15);
  transition: all 0.3s ease;
}

Pseudo-elements¶

Use pseudo-elements for decorative elements:

/* Add decorative border */
.notice::before {
  content: '';
  position: absolute;
  left: 0;
  top: 0;
  bottom: 0;
  width: 4px;
  background: var(--better-main);
}

Troubleshooting¶

Theme Not Applying¶

Check browser console for CSS errors
Verify CSS syntax is correct
Ensure selectors are specific enough
Check if !important is needed

Colors Not Changing¶

Verify you're using CSS variables
Check if forceDark is overriding your styles
Ensure variables are set on :root or html

Images Not Showing¶

Verify image variable name matches CSS
Check image format is supported
Ensure image size is reasonable
Verify url() wrapper in CSS

Dark Mode Issues¶

Test with forceDark: true and forceDark: false
Check if transparency effects are interfering
Verify html.dark selector is correct

Resources¶

Theme Creator: Access via BetterSEQTA+ settings
CSS Variables Reference: See CSS Variables section above
SEQTA DOM Structure: Inspect SEQTA pages in browser DevTools
BetterSEQTA+ Source: Check src/css/injected.scss for default styles

Contributing Themes¶

If you create a great theme, consider sharing it:

Export your theme (Share button in theme creator)
Submit to the BetterSEQTA+ theme store
Or share on GitHub/Discord

Note: This documentation is based on BetterSEQTA+ v3.4.13. Some details may change in future versions.