YourPropFirm Checkout Frontend

This repository is a WordPress add-on plugin (yourpropfirm-ui-addon) that overrides the UI layer of the YourPropFirm Plugin checkout experience. It contains CSS, JavaScript, and PHP templates — no backend logic, no payment processing, no REST endpoints.

Why a plugin instead of editing the main plugin directly? The main plugin will be updated over time, and direct edits would be overwritten. This add-on hooks in at a higher WordPress priority than the main plugin, so UI customizations survive any main plugin update automatically.

If you are a client frontend developer, this is the correct starting point. You do not need to touch the main plugin at all.

---

What's Included

Path	Description
src/css/	Tailwind 3 source files (checkout.css, components.css) — edit these
dist/css/	Compiled output (checkout.css) — committed to the plugin, do not edit directly
js/	Frontend scripts (checkout.js, dark-mode.js)
templates/	WooCommerce checkout PHP template overrides
build/	Node.js build tooling (package.json, tailwind.config.js, PostCSS config)
yourpropfirm-ui-addon.php	WordPress plugin entry point — registers hooks and constants
includes/	class-ypf-ui-addon-hooks.php — template and CSS override logic
scripts/	sync-from-plugin helpers to pull template updates from the main plugin
docs/	Extended reference docs (CSS_VARIABLES.md, TEMPLATE_REFERENCE.md, SYNC_WORKFLOW.md)

---

Prerequisites

• Node.js >= 18
• npm >= 9
• WordPress + WooCommerce + YourPropFirm plugin running locally (see Getting Started)
• Git

The recommended local WordPress environment is Local by Flywheel. The default checkout URL used throughout this project is http://yourpropfirm.local/checkout (plain HTTP — Local does not require HTTPS by default).

---

Installation as a WordPress Plugin

This repo is the WordPress plugin. Clone it directly into your plugins directory:

# Navigate to your WordPress plugins directory
cd /path/to/wp-content/plugins/

# Clone the repo
git clone https://github.com/QuantTechnologyGroup/yourpropfirm-ui-addon yourpropfirm-ui-addon

Then go to WordPress Admin → Plugins and activate YourPropFirm UI Addon.

The compiled CSS (dist/css/checkout.css) is already included in the repo — no build step required to get started. Node.js is only needed if you intend to edit the CSS source files.

The plugin requires the main YourPropFirm Plugin to be installed and active. It will show an admin notice if the dependency is missing.

To update to the latest version from this repo:

cd /path/to/wp-content/plugins/yourpropfirm-ui-addon
git pull origin main

---

Getting Started (Development)

1. Fork this repository on GitHub, then clone your fork into the plugins directory:

   cd /path/to/wp-content/plugins/
   git clone https://github.com/QuantTechnologyGroup/yourpropfirm-ui-addon yourpropfirm-ui-addon

2. Move into the build directory and install dependencies:

   cd yourpropfirm-ui-addon/build && npm install

3. Activate the plugin in WordPress Admin → Plugins → YourPropFirm UI Addon.

4. Start the CSS watcher. Tailwind will recompile dist/css/checkout.css on every save:

   npm run dev

5. Edit source files in src/css/, js/, or templates/ as needed. Reload the browser to see changes (CSS reloads automatically if the watcher is running).

6. Open http://ypf.local/checkout in your browser to test. The cart is auto-populated with a test product on every visit — no manual cart setup is required.

7. Before opening a pull request, produce a production-minified build:

   npm run build

8. Commit dist/css/checkout.css alongside your source changes, then submit a pull request. See Submitting a Pull Request for the required checklist.

---

CSS Architecture

Tailwind 3 with tw- prefix

All Tailwind utility classes are prefixed with tw- (e.g., tw-flex, tw-bg-yourpropfirm-primary). Every utility has !important applied automatically to prevent conflicts with the host WordPress theme. This is configured in build/tailwind.config.js and is not negotiable — do not remove these settings.

Dark mode

Dark mode is driven by a dark class on the <html> element, not by prefers-color-scheme alone. The toggle is managed by js/dark-mode.js and respects localStorage.theme with prefers-color-scheme as a fallback.

To style dark mode variants in source CSS:

/* in src/css/checkout.css or a component file */
.dark .my-component {
  background-color: var(--yourpropfirm-card);
}

Tailwind dark-mode utilities are also available via the dark: variant (e.g., dark:tw-bg-yourpropfirm-card).

Editing source CSS

• src/css/checkout.css — main entry point; contains :root CSS variable declarations, Tailwind directives, and page-level overrides.
• src/css/components.css — shared reusable component utilities. Add new component classes here inside an @layer components { } block.

Never edit dist/css/checkout.css directly. It is generated output.

Hardcoded hex values

Never hardcode hex colors. Always use an existing --yourpropfirm-* CSS variable or map to a Tailwind token. See Design Tokens.

---

Design Tokens

CSS variables are declared in src/css/checkout.css under :root (light theme) and .dark (dark theme overrides). The same names are wired into tailwind.config.js so they are available as Tailwind utility classes.

Variable	Usage
--yourpropfirm-primary	Brand accent color, primary buttons
--yourpropfirm-primary-hover	Hover state for primary buttons
--yourpropfirm-primary-light	Subtle tint backgrounds, highlights
--yourpropfirm-secondary	Secondary actions, labels
--yourpropfirm-background	Page / outer background
--yourpropfirm-card	Card and panel surface color
--yourpropfirm-text	Default body text
--yourpropfirm-button-text	Text color on filled buttons
--yourpropfirm-border	Default border color
--yourpropfirm-success	Success states, confirmations
--yourpropfirm-warning	Warning states
--yourpropfirm-error	Error / destructive states
--yourpropfirm-border-standby	Inactive / disabled border
--yourpropfirm-progressbar-from	Progress bar gradient start
--yourpropfirm-progressbar-to	Progress bar gradient end

For the full variable listing, default values, and guidance on adding new tokens, see docs/CSS_VARIABLES.md.

---

JavaScript

js/checkout.js

Handles all interactive checkout behavior:

• Coupon logic — applies and removes WooCommerce coupon codes via AJAX without a full page reload.
• Auto-fill — pre-populates checkout fields from known user data on page load.
• AJAX requests — communicates with the plugin back end using WordPress wp_ajax_* actions. Do not rename these action strings.

Global PHP objects available to this script:

Object	Description
yourpropfirm_purchase	Localized data about the current purchase (product, pricing, user context)
ypfCheckoutStore	Reactive store for checkout state (selected bundle, coupon status, etc.)

Both objects are injected via wp_localize_script in the plugin. Their structure is documented in the plugin source — do not redefine or shadow them from frontend JS.

js/dark-mode.js

Manages theme switching. Exposes a public API at window.YourPropFirmTheme:

window.YourPropFirmTheme.toggle()   // flip between light and dark
window.YourPropFirmTheme.setDark()  // force dark
window.YourPropFirmTheme.setLight() // force light
window.YourPropFirmTheme.current()  // returns 'dark' | 'light'

Preference is persisted to localStorage.theme. On first visit, prefers-color-scheme is read as the default.

---

PHP Templates

The templates/ directory contains WooCommerce checkout template overrides. These follow WooCommerce's standard override convention: files here take precedence over WooCommerce core templates at the matching path.

Plugin-specific sections (bundles, add-ons, progress bar, etc.) live in templates/partials/checkout/ and are included from the main checkout template.

For a full list of available template files, the hooks they expose, and the PHP variables injected into each, see docs/TEMPLATE_REFERENCE.md.

---

What You Can and Cannot Change

SAFE to modify

• Colors, spacing, typography, and border styles via CSS variables or Tailwind utilities
• HTML markup structure within template files (adding/removing elements, reordering sections)
• Dark mode selectors (.dark .element { })
• Visible user-facing text, provided you wrap it in a WordPress translation function (__(), _e(), esc_html__(), etc.)
• New @layer components entries in src/css/components.css
• New CSS variable tokens (add to :root and .dark in src/css/checkout.css, then extend tailwind.config.js)

DO NOT change

• WooCommerce action and filter hooks (do_action('woocommerce_checkout_*'), apply_filters(...)) — removing or reordering these breaks payment processing and order submission
• CSS class selectors referenced by JavaScript — if checkout.js targets a class, renaming that class in CSS/HTML will silently break behavior
• data-sub-section attributes — used by the AJAX reload mechanism to patch DOM fragments; renaming them causes partial-page updates to fail
• AJAX action names — string literals like ypf_apply_coupon are registered server-side; changing them client-side breaks the request routing
• Global JS object names (yourpropfirm_purchase, ypfCheckoutStore) — these are injected by PHP and consumed across multiple scripts; do not shadow or reassign them

---

Day-to-Day Workflow

Because this repo is the WordPress plugin, no sync step is needed. Any changes you make are immediately live in WordPress.

What you're changing	Build step needed?
PHP templates (templates/)	No — reload browser
JavaScript (js/)	No — reload browser
CSS source (src/css/)	Yes — run npm run dev or npm run build

Editing CSS:

# One-time setup (only needed once after cloning)
cd build && npm install

# Watch mode — auto-recompiles dist/css/checkout.css on every save
npm run dev

Committing changes:

# If you edited CSS, build production output first
cd build && npm run build

git add -A
git commit -m "feat: describe your change"
git push origin main

---

Submitting a Pull Request

1. Create a feature branch from main:

   git checkout -b feat/your-description

2. Make your changes, keeping commits focused and descriptive.

3. Run a production build before pushing:

   cd build && npm run build

   The compiled dist/css/checkout.css must be committed alongside your source changes.

4. Push your branch and open a pull request against main.

PR checklist

Your PR description must include:

• A clear summary of what changed and why
• Screenshots showing the affected UI in both light mode and dark mode
• The WooCommerce version you tested against (e.g., WooCommerce 8.x)
• Confirmation that npm run build completed without errors and the compiled CSS is committed

PRs that are missing screenshots or that include uncommitted source-only changes (no compiled output) will be returned for revision.

---

License

GPL-2.0+

This project is licensed under the GNU General Public License v2.0 or later, consistent with WordPress and WooCommerce licensing requirements.