Skills Shop Portal Build Principles
Core Rule
Rebuild properly, not quickly. When the use tell you to “do the build” or “go” you should not instantly produce the package. Take your time building properly.
Do not copy old systems unless they are still the best solution.
Every feature must justify its place through simplicity, speed, usability and maintainability.
If something feels clunky, crowded, slow or confusing, redesign it.
No patch should be allowed to become permanent unless it is clean, reusable and documented.
Build Method
Each module is developed in phases.
For every phase:
1. Define the business goal
2. Review the old approach
3. Check the current plugin structure
4. Recommend better architecture
5. Ask only key decisions
6. Build a stable release
7. Test before next phase
Never rush straight into code without first improving the thinking.
Architecture Rule
The portal must be modular.
Large single files should not be allowed to grow unchecked.
CSS, JavaScript and PHP should be split by purpose when it improves clarity, speed or maintainability.
Use clear file groups:
Core:
– tokens
– layout
– typography
– buttons
– cards
– forms
– utilities
Modules:
– CRM
– project pane
– accounts
– contacts
– notifications
– learning hub
– tasks
– settings
Shared code must live in shared files.
Module-specific code must live inside that module.
Do not add new code to an old bloated file just because it is easy.
CSS Rule
CSS must be clean, modular and token-led.
No duplicate selector blocks unless there is a clear reason.
No layered fixes on top of old fixes.
No repeated version patch sections left behind.
No unnecessary !important rules.
No one-off colours.
No random blue backgrounds.
No styling battles.
Every visual component must have one source of truth.
Before changing CSS, check whether the selector already exists.
If a style is replaced, remove the old style.
Core visual styles should come from shared tokens:
– colour
– typography
– spacing
– radius
– shadow
– border
– icon size
– button height
– pill height
A small change should not need a large override.
JavaScript Rule
JavaScript must be split by responsibility.
Do not create one large controller for everything.
Use clear modules:
– portal core
– CRM controller
– project pane
– notifications
– learning hub
– settings
– utilities
Avoid duplicate event listeners.
Avoid duplicate render logic.
Avoid re-rendering whole screens when only one component changed.
Keep functions small enough to understand.
If a function becomes difficult to scan, split it before adding more logic.
PHP Rule
PHP should stay service-based and modular.
Each class should have a clear job.
Avoid mixing:
– rendering
– saving
– migration
– validation
– permissions
– settings
Use shared services for repeated logic.
Do not duplicate database queries across modules.
Any large class should be reviewed before adding more code.
Legacy Code Rule
No legacy code should remain just because it still exists.
When replacing a layout, controller, style or component:
1. Find the old version
2. Check if it is still used
3. Remove it if not needed
4. Keep a rollback ZIP instead of keeping dead code
5. Add a changelog note
Commented-out old systems should not stay in production files.
Old code creates future bugs.
File Size Rule
File size should be monitored before each major build.
If a file becomes hard to scan, it must be split.
Warning signs:
– CSS file over 100 KB
– JS file over 150 KB
– PHP class over 50 KB
– repeated selectors
– repeated functions
– lots of !important rules
– multiple version patch sections
Large files are not banned, but they must justify their size.
Single Source of Truth Rule
There should be one source of truth for every system.
Examples:
– one notification bell style
– one button system
– one pill system
– one top bar layout
– one project pane structure
– one activity composer
– one milestone engine
– one course mapping source
– one certificate mapping source
If two systems do the same job, one should be removed.
UI Rule
Think like Apple would build it.
The portal must feel calm, minimal and obvious.
Every screen should have one clear purpose.
Do not show duplicate data.
Do not add controls just because they are possible.
Everything must have a natural place.
If a user has to stop and think, the design needs improving.
Would this feel obvious in 3 seconds? If not, simplify it.
Layout Rule
Every core pane should follow the same structure:
1. Top bar
2. Smart row
3. Focus area
4. Supporting panel only if needed
No screen should begin with random cards, dense forms or cluttered tables.
The first view should guide decisions, not overwhelm.
Top Bar Rule
The top bar is for identity and primary actions.
It should stay calm, clean and consistent.
Primary actions belong on the right.
Search, create, refresh and notifications should align as one command area.
Notification bell rules:
– white background
– #004165 bell icon
– #0cc6de badge background
– white badge number
– badge only appears when count is greater than zero
Do not create floating duplicate action docks unless there is a strong reason.
Smart Row Rule
Smart rows must only show useful information.
Hide anything that is:
– zero
– empty
– all clear
– duplicate
– not actionable
Every smart item must either:
– explain something important
– open something useful
– prompt an action
If a metric is shown, it should have a reason to exist.
Clickable Insight Rule
If a number, warning or summary is shown, it must be clickable where practical.
Examples:
Warnings 5
Revenue Due £11,277
Waiting 2
Clicking should open the relevant list, drawer or focus view.
No dead metrics.
No Scroll First View Rule
The first view of any core pane should avoid scrolling wherever possible.
Scrolling is acceptable only for:
– full edit forms
– long activity history
– detailed audits
– settings
– archives
The default screen should fit key decisions above the fold.
Typography & Visual System Rule
All widgets, cards, rows, chips, buttons and modules must follow the shared design system.
Use standard typography tokens for:
– headings
– sub headings
– body text
– meta text
– labels
– buttons
Use shared spacing, borders, shadows and corner radius.
Do not introduce random colours, blue backgrounds or one-off styles.
Visual hierarchy must come from typography, spacing and contrast first.
Colour should be used with purpose only.
Settings Rule
Never use one bloated settings page.
Use:
– Global settings in sidebar footer cog
– Module settings inside each module only when needed
Settings should feel lightweight and contextual.
Performance Rule
Every build must reduce complexity, duplicate Ajax, duplicate CSS and unnecessary rendering.
Remove old layouts when replaced.
Reduce visual clutter and code clutter together.
Use shared components before creating new ones.
Fast feels premium.
One user action should not trigger multiple unnecessary requests.
If several small Ajax calls always happen together, consider batching them.
Conflict Prevention Rule
Before every build, check for:
– duplicate CSS selectors
– duplicate JS event handlers
– duplicate render functions
– conflicting button styles
– conflicting top bar styles
– old layout blocks still being loaded
– unused files still being enqueued
– stale version references
Do not build on top of a conflict.
Fix the conflict first.
Data Safety Rule
Any migration or database change must never run blind.
Always provide:
1. Audit preview first
2. No-change dry run
3. Exact warnings shown
4. Manual confirmation
5. Rollback path where possible
Protect live data at all times.
Release Rule
Every release must include:
– version update
– changelog update
– PHP lint check
– JS syntax check
– ZIP structure check
– no missing required files
– no duplicate top-level plugin folder
– quick scan for obvious CSS conflicts
A release should be stable, installable and explainable.
Future Rule
Build for expansion.
Every phase should support future modules without rework.
Today’s solution should not block tomorrow’s module.
Think system, not page.
Final Test Before Release
Ask:
– Is it simpler?
– Is it faster?
– Is it clearer?
– Is it consistent?
– Is it needed?
– Is there duplicate code?
– Is there old code fighting new code?
– Would Steve Jobs approve?
If not, improve before release.