From 197a564733d58830d403990cc29d4839e8ee4dcf Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Tue, 30 Dec 2025 16:00:49 +0000
Subject: [PATCH] Improve documentation and add error handling for palette
 utility functions

Co-authored-by: Kinneyzhang <38454496+Kinneyzhang@users.noreply.github.com>
---
 tp-palette.el | 28 ++++++++++++++++++++++------
 tp.el         |  4 +++-
 2 files changed, 25 insertions(+), 7 deletions(-)

diff --git a/tp-palette.el b/tp-palette.el
index 3613566..70403d5 100644
--- a/tp-palette.el
+++ b/tp-palette.el
@@ -745,17 +745,33 @@
 
 ;;; Utilities
 
+(defun tp-palette--get-color (symbol key)
+  "Get color value for KEY from palette SYMBOL.
+SYMBOL should be a symbol bound to a palette plist.
+KEY should be one of :fg, :bg, or :border.
+Returns nil if SYMBOL is unbound or doesn't contain KEY."
+  (when (and (symbolp symbol) (boundp symbol))
+    (let ((plist (symbol-value symbol)))
+      (when (plistp plist)
+        (tp-parse-color (plist-get plist key))))))
+
 (defun tp-palette-fg-color (symbol)
-  "Get the foreground color from palette SYMBOL."
-  (tp-parse-color (plist-get (symbol-value symbol) :fg)))
+  "Get the foreground color from palette SYMBOL.
+SYMBOL should be a symbol bound to a palette plist with a :fg key.
+Returns nil if SYMBOL is unbound or doesn't contain :fg."
+  (tp-palette--get-color symbol :fg))
 
 (defun tp-palette-bg-color (symbol)
-  "Get the background color from palette SYMBOL."
-  (tp-parse-color (plist-get (symbol-value symbol) :bg)))
+  "Get the background color from palette SYMBOL.
+SYMBOL should be a symbol bound to a palette plist with a :bg key.
+Returns nil if SYMBOL is unbound or doesn't contain :bg."
+  (tp-palette--get-color symbol :bg))
 
 (defun tp-palette-border-color (symbol)
-  "Get the border color from palette SYMBOL."
-  (tp-parse-color (plist-get (symbol-value symbol) :border)))
+  "Get the border color from palette SYMBOL.
+SYMBOL should be a symbol bound to a palette plist with a :border key.
+Returns nil if SYMBOL is unbound or doesn't contain :border."
+  (tp-palette--get-color symbol :border))
 
 (provide 'tp-palette)
 ;;; tp-palette.el ends here
diff --git a/tp.el b/tp.el
index bd78df0..62440c3 100644
--- a/tp.el
+++ b/tp.el
@@ -124,7 +124,9 @@ This is a list of (LAYER-NAME . CHANGED-VARS) pairs pending update.")
     yank-handler auto-composed evaporate face-alias)
   "List of built-in Emacs text property names.
 These property names are reserved and cannot be used as layer names in `define-tp'.
-Layer names that conflict with these will cause errors during text property operations.")
+An error is signaled at macro expansion time (when the `define-tp' form is
+evaluated) if a reserved name is used, preventing the layer definition from
+being created.")
 
 (defun tp--builtin-text-property-p (name)
   "Return non-nil if NAME is a built-in text property name.