<Panel title="My Titile" titleDisplay="Your Title" />
Are you using an IDE? There are certain things that you just can't worry about and this is one. Any Flex compiler should throw an error with the above. Setting a String on the titleDisplay property is like trying to assign a String to a Boolean, it won't compile.
Although, I can see where someone could try to set a visual element into the titleDisplay which would wipe out the reference on the Panel and screw things up from there.
Since Adobe is creating majik with SkinParts anyway, they should really start to think about more compiler errors when developers do try to use SkinPart variables. in a write fashion (actionscript would not work so well but MXML could).
Other than that, your developers should know the API or at least read the asdocs.
You're right... that wouldn't get past the compiler since titleDisplay is a TextBase object. There is also controlBarGroup and controlBarContent, and you're supposed to use controlBarContent. I followed Panel's implementation in creating my own component with many groups such as headerContent, footerContent, userManagementContent etc... the skin file decides layout and design--SWEET---designers will be able to make design tweaks throughout development!
The concern one of my colleagues has is that a developer might inadvertently use a skin part (enterprise environment and several large distributed product teams working without much direct communication). He wants it to be dead simple, no confusion, (while maintaining a consistent look and feel), but I see that this is really a basic understanding of the API, and common for any composition based architecture in general. The public properties are required to keep components loosely coupled from design/layout, right?
Sounds like I need to push back a bit... and regarding consistent look and feel... well, hiding the skin parts somehow would never help because anyone could easily just create a new skin file. And thats the point.